> 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/platform/gateway.md).

# The Gateway

What the gateway enforces on every call: identity, organization context, authorization, rate limits, billing, audit, dispatch.

> **Auth · Org · Authorization · Rate · Billing · Audit — before any tool runs.** The gateway is the single enforcement chain. Every tool call, every surface, every caller... They all converge here.

***

## What the gateway is

A single deterministic enforcement chain in front of every runtime. Calls enter on the canonical public ingress; the gateway runs each stage in order; only after the chain passes does the call reach the runtime that owns the tool.

```
Client → Gateway:
  Identity → Org context → Authorization → Rate limit → Billing → Audit → Dispatch
                                                                    ↓
                                                   The owning runtime executes
                                                                    ↓
                                              Response (with X-Trace-Id) ← back to client
```

The gateway is where "can this call run at all?" is decided — the only place in the system that answers the question.

***

## The enforcement chain

| Stage                    | What it enforces                                                                                                                                        | Failure mode                                                                             |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| **Identity**             | Auth0 bearer token verified server-side. Auth0 is the sole identity provider.                                                                           | 401 with trace ID.                                                                       |
| **Organization context** | Tenant boundary derived from the authenticated principal — never from a client header.                                                                  | Structured refusal with trace ID.                                                        |
| **Authorization**        | Per-tool, per-org permission check against the governed authorization model. Authorization runs *before* rate limiting.                                 | 403 with trace ID.                                                                       |
| **Rate limiting**        | Per-org throttling. Protects shared capacity from a single tenant burst.                                                                                | 429 with trace ID.                                                                       |
| **Billing**              | Credit ledger check against the organization's wallet. Calls that would exceed available credits are stopped here, before the runtime sees the request. | Deterministic billing-failure envelope with trace ID; the agent can re-plan or escalate. |
| **Audit**                | Every governed call — allowed or refused — produces an immutable, trace-correlated audit row.                                                           | N/a — a refusal is itself audited.                                                       |
| **Dispatch**             | Transport of the approved, prepared call to the runtime that owns the tool.                                                                             | Transport-error envelope with trace ID.                                                  |

Authorization-before-rate-limit is intentional. A tool that the caller has no permission to invoke is a 403 long before it can affect the shared rate-limit budget.

***

## How credentials flow

Credentials are handled by the platform, resolved inside the gateway before dispatch. The contract is:

* **Credentials are resolved server-side per call and injected by the gateway, scoped to a single invocation.** Tools and agents never receive access to Mediafier's credential stores.
* **Tools never return credential material.** The narrow exception is a pair of approval-gated provisioning surfaces whose purpose is to issue a credential: each returns a newly issued secret exactly once, to its owner, after organization-admin approval — and never re-reveals it.
* **Secrets stay out of agent payloads and runtime logs.**

## What the gateway always enforces

Three commitments that hold for every call:

* **Server-derived tenant context.** Organization is resolved from the authenticated principal, never from a client-supplied header. The boundary is decided by the platform, not by the caller.
* **One enforcement chain.** Every call walks the same stages in the same order. No service-account fast-path, no internal client mode, no exemption for partner runtimes — which is what makes the chain auditable end to end.
* **Credential isolation.** Credentials are resolved where tools, agents, and runtimes cannot reach them, and secrets stay out of agent payloads and runtime logs — see "How credentials flow" above.

***

## Trace correlation

Every response — success or error — carries an `X-Trace-Id` header. The same ID:

* Lands in the audit log for the call.
* Threads through the billing ledger.
* Propagates as a header to the runtime that executes the call, so its logs pivot on the same key.
* Appears inside structured error envelopes returned to the agent.

A customer-support engineer who has the trace ID can reconstruct the entire call path: who, when, which org, which tool, what input, what the runtime returned, how much it cost.

***

## Public endpoints

```
POST https://mcp.mediafier.ai/mcp
```

The canonical multiplexed ingress, callable from any MCP-aware client. All public traffic is JSON-RPC over HTTPS. (An advanced scoped per-server form exists for harnesses that need a single-server session — see [MCP Access](/connect/mcp-access.md).)

***

## Where to go next

| If you're…                           | Read next                                                                                                                                        |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| New to the platform                  | [What is Mediafier?](/overview/what-is-mediafier.md)                                                                                             |
| Looking for the broader architecture | [Platform Architecture](/platform/platform-architecture.md)                                                                                      |
| Looking for client integration       | [Agent-First Access (CLI + MCP)](/connect/agent-first-access.md)                                                                                 |
| Studying the discovery model         | [Governed Resources & Discovery](/platform/governed-resource-substrate.md)                                                                       |
| Auditing identity and tenancy        | [Identity & Authentication](/trust/identity-and-authentication.md), [Multi-Tenant Organization Model](/trust/multi-tenant-organization-model.md) |