> For the complete documentation index, see [llms.txt](https://docs.mediafier.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mediafier.ai/trust/identity-and-authentication.md).

# 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:

1. **Who issues identity?** Auth0, full stop.
2. **How is identity trusted at the gateway?** A bearer access token verified server-side at the gateway entry, before any tool call runs.
3. **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…                                    | Read next                                                                         |
| --------------------------------------------- | --------------------------------------------------------------------------------- |
| Looking at how tenants are isolated           | [Multi-Tenant Organization Model](/trust/multi-tenant-organization-model.md)      |
| Studying the gateway's full enforcement chain | [The Gateway](/platform/gateway.md)                                               |
| Auditing observability and trace correlation  | [Audit, Observability & Compliance](/trust/audit-observability-and-compliance.md) |
| Engineering an integration                    | [Agent-First Access (CLI + MCP)](/connect/agent-first-access.md)                  |