> 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/connect/authentication.md).

# Authentication & Agent Credentials

Browser sign-in for interactive sessions; Agent Credentials exchanged for access tokens for headless use; scopes and rotation.

> **One identity model, two ways to obtain a token.** Interactive sessions sign in through the browser; headless and CI workloads use an organization agent credential with the OAuth client-credentials flow. Either way the gateway receives a bearer access token, and Mediafier resolves who you are — and which organization you act for — on the server.

***

## Choosing a path

| Your context                         | Use                                                                   |
| ------------------------------------ | --------------------------------------------------------------------- |
| Connecting an MCP-aware agent or IDE | **Browser sign-in** (most clients self-register)                      |
| Headless scripts, CI, or a server    | **Organization agent credential** (client credentials → bearer token) |

You never set an organization or tenant header on a request. Org context is derived from your token.

***

## Interactive sign-in

Most agent and IDE clients handle sign-in themselves: they register with the gateway and open a browser sign-in the first time you connect. There is no credential to paste, and the client refreshes the session for you.

***

## Headless: Agent Credentials

For automation, CI, or a server with no browser, create an organization agent credential. It is an OAuth client credential (a client ID and a secret), not a gateway token: exchange it for a bearer access token with the OAuth client-credentials flow, then present that token. The Agent Card at `https://mcp.mediafier.ai/.well-known/agent.json` publishes a `machine_credentials` block with the token endpoint, the audience to request, and the client authentication method — that block, not the interactive authorization-server metadata, is the contract for this exchange.

### Create an Agent Credential

An organization admin creates one in the Mediafier app under **Settings → Organization → Agent Credentials** (`app.mediafier.ai/settings/org/api-keys`): give it a label, the scopes it needs, and an expiry.

The secret is shown **once, at creation time**, and is never retrievable afterward. Copy it into your secret manager immediately. Listing keys shows metadata only (label, scopes, created, expires, last used, status) — never the secret.

### Exchange it for an access token

This is a standard OAuth client-credentials request, form-encoded (`client_secret_post`). Read the token endpoint and audience from the Agent Card rather than hard-coding them, and keep the client ID and secret in environment variables from your secret manager:

```bash
CARD=$(curl -s https://mcp.mediafier.ai/.well-known/agent.json)
TOKEN_ENDPOINT=$(echo "$CARD" | jq -r .machine_credentials.token_endpoint)
AUDIENCE=$(echo "$CARD" | jq -r .machine_credentials.audience)

export MEDIAFIER_TOKEN=$(curl -s "$TOKEN_ENDPOINT" \
  --data-urlencode grant_type=client_credentials \
  --data-urlencode client_id="$MEDIAFIER_CLIENT_ID" \
  --data-urlencode client_secret="$MEDIAFIER_CLIENT_SECRET" \
  --data-urlencode audience="$AUDIENCE" | jq -r .access_token)
```

The response carries `access_token`, `token_type` (`Bearer`) and `expires_in` (seconds). **Reuse the token until it expires** — request a new one shortly before `expires_in` runs out, not once per call; token requests are rate-limited.

### Present the token

Send the access token as the bearer on every MCP request:

```
Authorization: Bearer <MEDIAFIER_TOKEN>
```

For example, list the tools your organization can call:

```bash
curl -s https://mcp.mediafier.ai/mcp \
  -H "Authorization: Bearer ${MEDIAFIER_TOKEN}" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

To use the token from your own TypeScript or Python code, see [MCP Access](/connect/mcp-access.md#your-own-code-typescript-python).

The credential secret itself belongs in your secret manager only; the gateway does not accept it directly — only the access token.

### Rotate and revoke

On the same Agent Credentials page:

* **Regenerate** issues a new secret and keeps the old one working for a short grace window, so you can cut over without downtime.
* **Revoke** disables a credential immediately.

The list shows metadata only; a secret is shown solely on creation and on regeneration, and only once.

***

## Scopes and least privilege

Grant a key only the scopes it needs. A key scoped to read-only discovery cannot invoke tools; a key scoped for a single workload should not carry broad access. Narrow scopes limit blast radius if a key leaks.

***

## What stays server-side

* **Identity** is verified on every call.
* **Organization context** is derived from your token — never trusted from a client header.
* **Authorization, rate limiting, billing, and audit** run before any tool executes.

If a call is rejected, the response carries a trace identifier so support can correlate it.

***

## Next steps

* [Getting Started](/connect/getting-started.md) — connect, sign in, first call.
* [MCP Access](/connect/mcp-access.md) — setup for a specific client.