> ## Documentation Index
> Fetch the complete documentation index at: https://docs.molesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Security and multi-tenancy

> Tenant isolation, capability authorization, platform scope, tokens, audit, sharing, secrets, and field encryption.

MoleSignal applies tenant and authorization controls in the API and data plane, below the web
navigation.

## Tenant isolation

Every organization stream and product resource has an owning `org_id`. Query planning injects the
authorized organization boundary before execution. Resource handlers also load the target and
verify the organization before reads or mutations.

Cross-workspace access must use an explicit IAM grant or supported resource share. A mismatched
resource lookup does not silently switch organizations.

The `_sys` organization is a protected platform scope. Tenant JWTs and `ms_*` API tokens cannot
enumerate licenses, platform administrators, or MoleSignal self-telemetry.

## Authentication and authorization

MoleSignal accepts:

* login JWTs, including newly scoped JWTs after a workspace switch;
* API tokens shaped `ms_<prefix>_<secret>`;
* dedicated self-authenticating tokens for narrowly scoped public or integration routes.

The API-token prefix is stored for lookup, and the secret is hashed. The complete token is shown
only at creation.

After authentication, the server resolves database-backed permissions, roles, bindings, resource
relationships, license features, and target ownership. See [Identity & access](/en-US/identity).

## JWT signing keys

JWT signing keys are bootstrapped into the database. Raw key bytes are never returned by the
metadata endpoint.

Listing or rotating signing keys requires the platform permission `sys.settings.manage`:

```text theme={null}
GET  /api/v1/auth/jwt/secrets
POST /api/v1/auth/jwt/rotate
```

Use `MS_AUTH_JWT_SECRET_OVERRIDE` only when deployment policy requires a fixed bootstrap key.

## Audit

Security-relevant and product mutation paths record actor, organization, action, target, time, and
safe metadata. Query organization events under **Settings → Audit** with `audit.read`.

License packages, credentials, model keys, sensitive webhook headers, and raw signing material are
excluded from audit payloads.

## Resource sharing

Public dashboard and report links are bearer credentials, but public links do not become organization
tokens. MoleSignal exchanges a link for a short-lived HttpOnly share session and constrains access
to one saved resource.

Public dashboard panels can execute only server-stored queries through a restricted proxy. Shares
can expire, require a password, enforce a maximum view count, disable downloads, and be revoked or
rotated. See [Resource sharing](/en-US/resource-sharing).

## Field-level encryption

Organization cipher keys support AES-256-GCM field encryption. The cipher root key comes from
`MS_CIPHER_KEY`; named key material is not returned after creation.

Use VRL encryption functions on intake and matching decryption on authorized query paths. Reading
key metadata requires `org.settings.read`; creating, rotating, or deleting keys requires
`org.settings.manage`.

<Warning>
  Losing `MS_CIPHER_KEY` can make encrypted fields unrecoverable. Store the key in a secrets manager
  and back up the key independently of PostgreSQL and object storage.
</Warning>

## Secret and telemetry hygiene

* Store database, object-store, SMTP, SSO, model-provider, and webhook credentials in a secret
  manager.
* Use `env:` or `secret:` references for sensitive external trace-export headers.
* Keep internal gRPC `5082` on a trusted network because the port includes cluster protocols.
* Put TLS in front of external HTTP, OTLP gRPC `4317`, and Flight SQL `5083`.
* Keep the pprof listener on loopback unless remote diagnostics are explicitly protected.
* Backend tracing excludes request bodies, SQL values, credentials, prompts, model output, and
  tool arguments.

## Rate and service controls

The router applies per-organization intake and query token buckets. Storage and daily intake limits
can also come from deployment or license policy. A suspended subscription can return `402`; rate
limits return `429`, and oversized or storage-limited writes can return `413`.

<Card title="Self-observability" icon="heart-pulse" href="/en-US/self-observability">
  Configure protected `_sys` telemetry, tail sampling, and node-local diagnostics.
</Card>