Identity & Authentication

How identity is issued and verified, how organization context is derived server-side, and what an identity failure returns.

Auth0 is the sole identity provider. The gateway resolves the caller server-side. There is no client-trusted identity claim anywhere on the platform.

Three questions every security reviewer asks

Each is answered below:

Who issues identity? Auth0, full stop.
How is identity trusted at the gateway? A bearer access token verified server-side at the gateway entry, before any tool call runs.
What about the caller's organization? The gateway derives tenant context from the authenticated principal — never from a client-supplied header, query param, or body field.

The identity boundary

Mediafier draws one identity boundary and reuses it across every surface — agent-first (CLI + MCP), Slack & Teams, and Pippa chat.

External caller (any surface)
   │
   ▼  bearer access token
┌─────────────────────────────────────┐
│  Gateway: Identity stage            │
│  - Verify Auth0 token server-side   │
│  - Resolve principal                │
│  - Derive organization from claims  │
└─────────────────────────────────────┘
   │
   ▼  authenticated request context
Authorization → Rate → Billing → Audit → Dispatch

Whatever surface the caller uses, the request reaches the gateway with an Auth0 bearer token. The gateway verifies it server-side and resolves the principal. From that principal, the gateway derives the organization context that every later stage uses.

Why Auth0 is the sole identity provider

A single identity provider is what makes the rest of the chain defensible:

One verification path. The gateway has exactly one way to resolve a caller's identity. There is no service-account fast-path, no internal client mode, no per-runtime auth shim.
Centralized session policy. Token lifetime, refresh, MFA, and session revocation are governed at the identity provider, not at each surface.
Federated tenant identity. Customers who run their own SSO federate it into Auth0 and get the same gateway behavior; their agents land in the same enforcement chain as everyone else.

Every surface reaches Mediafier through the same Auth0-issued identity contract. There is no separate path with a different identity model.

Tenant context is server-derived

Every authenticated request carries an organization context. That context is never taken from the client.

Tenant context derives exclusively from the authenticated principal, resolved server-side. No client-supplied header, body field, or query parameter is ever consulted for organization identity — they are payload, not identity claims. Users who belong to multiple organizations select one per session, and that selection is validated server-side against the memberships Mediafier governs.

The practical effect: a caller who tampers with a header to claim another org gets the original org's authorization decision anyway. There is no path through the gateway where the client picks the tenant.

What the gateway returns on identity failure

Every identity failure produces a structured response:

HTTP 401 if the token is missing, malformed, expired, or fails signature verification.
A structured refusal if the token is valid but the principal cannot be resolved to an active Mediafier organization — the error code and machine-readable actions say what to do next.
An X-Trace-Id header (and trace_id in the error body) on every failure, so support can pivot from the response to the audit chain without the caller having to share a token or principal.

The error envelope is the same shape every surface returns. An agent seeing a 401 from Mediafier knows exactly what to do: authenticate (or refresh its access token) and re-call. An operator inside Pippa seeing the same outcome gets the same machine-readable signal under the chrome.

How credentials and data are protected

Assurances a security reviewer can rely on, each scoped to what it actually covers:

Encryption in transit. All platform traffic runs over HTTPS.
Encryption at rest. Platform data stores are encrypted at rest at the infrastructure layer.
Application-level credential encryption. Stored organization credentials are additionally encrypted at the application layer (AES-256-GCM) before they reach the data store — infrastructure encryption is not the only layer protecting a secret.
Credential redaction. Credential material does not appear in tool responses, error envelopes, or audit artifacts. The audit trail records who acted and what happened — never secret bytes.

What this page is not

It is not the ops runbook for SSO setup. Customers configuring enterprise SSO follow the partner-facing onboarding.
It is not a description of how Auth0 itself works. The authoritative reference for that is Auth0's documentation. This page is about the contract between Auth0 and the Mediafier gateway.
It is not the only page that talks about identity. Identity is a thread that runs through audit, billing, and authorization.

Where to go next

If you're…