> 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                                                                   |
| ------------------------------------- | --------------------------------------------------------------------- |
| Working from a terminal               | **Browser sign-in** via the CLI                                       |
| Connecting an MCP-aware agent harness | **Browser sign-in** (most harnesses 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

From the CLI, sign in through your browser:

```bash
mediafier auth login
```

The CLI stores and refreshes the session for you. Check status or sign out:

```bash
mediafier auth status
mediafier auth logout
```

Most agent harnesses handle sign-in themselves: they register with the gateway and open a browser sign-in the first time you connect. No credential to paste.

***

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

```bash
mediafier auth keys create --label "ci-pipeline" --scopes read,invoke --expires-in 90d
```

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.

### Use an Agent Credential

Exchange the credential for an access token (client-credentials grant), then present the access token as the bearer. In a request header:

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

In a shell, reference the access token from the environment so it never appears in your command:

```bash
export MEDIAFIER_TOKEN=<access-token>
mediafier tools list
```

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

### Rotate and revoke

Rotate with a grace window so the old key keeps working until the cutover completes:

```bash
mediafier auth keys regenerate <key-id> --grace 24h
mediafier auth keys revoke <key-id>
```

Listing and rotating project metadata only; the secret is returned solely on the original `create` (and on `regenerate`), 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) — install, connect, first call.
* [CLI](/connect/cli-reference.md) — the full `auth` command group.