> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ezforge.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> API keys, session tokens, and OAuth 2.1 for MCP clients

ezForge uses two separate auth systems:

1. **Platform auth** — authenticates *you* (the developer) to the ezForge API and CLI
2. **MCP auth** — authenticates *MCP clients* (AI assistants) to your deployed servers

## Platform authentication

### API keys

API keys are scoped, revocable credentials for programmatic access to the ezForge control plane.

**Create an API key** in the dashboard under **Project → API Keys**, or via the CLI:

```bash theme={null}
ezforge project create-key my-first-project --name "ci-deploy" --scopes "deployments:write,servers:read"
```

Keys use the prefix `ezf_live_` (production) or `ezf_test_` (test environment).

**Available scopes:**

| Scope               | Description                    |
| ------------------- | ------------------------------ |
| `servers:read`      | List and view servers          |
| `servers:write`     | Create, update, delete servers |
| `deployments:read`  | View deployment history        |
| `deployments:write` | Trigger deploys and rollbacks  |
| `logs:read`         | Stream server logs             |
| `metrics:read`      | View server metrics            |
| `billing:read`      | View billing and usage         |

**Using an API key:**

```bash theme={null}
curl -H "Authorization: Bearer ezf_live_..." https://api.ezforge.ai/v1/projects
```

### Session tokens

The ezForge CLI and dashboard use session-based auth (HTTP-only cookies, 1-hour expiry). Use `ezforge auth login` to authenticate the CLI.

## MCP authentication

Every deployed MCP server is protected by **OAuth 2.1 with mandatory PKCE** (S256 code challenge method). This means MCP clients must complete an authorization flow before they can call your server's tools.

### ezforge\_managed mode (default)

ezForge acts as the OAuth authorization server. No configuration needed — your server is protected out of the box.

**Client registration — two paths:**

| Path                 | When to use                                                    |
| -------------------- | -------------------------------------------------------------- |
| **CIMD** (preferred) | Your client can host a metadata document at a stable HTTPS URL |
| **DCR** (fallback)   | Your client cannot host a metadata document                    |

**CIMD (Client ID Metadata Document)** — the MCP spec's preferred path. Your client uses its own metadata URL as `client_id`. ezForge auto-fetches and registers the client on first authorization request. No separate registration call required.

**DCR (Dynamic Client Registration, RFC 7591)** — POST metadata to `/api/v1/servers/:id/clients` or include `clientMetadataUrl` in the body for CIMD explicit pre-registration.

MCP clients discover auth metadata via the standard `.well-known` endpoints:

```
GET https://app.ezforge.ai/.well-known/oauth-authorization-server
```

This returns RFC 8414 Authorization Server Metadata, including `"client_registration_types_supported": ["automatic"]`, signalling CIMD support.

MCP clients also discover protected resource metadata via:

```
GET https://{slug}.mcp.ezforge.ai/.well-known/oauth-protected-resource
```

Response:

```json theme={null}
{
  "resource": "https://my-server.mcp.ezforge.ai",
  "authorization_servers": ["https://app.ezforge.ai"],
  "scopes_supported": ["mcp:read", "mcp:write", "mcp:execute", "offline_access"],
  "bearer_methods_supported": ["header"]
}
```

### BYOA mode (Bring Your Own Auth)

If you have an existing OAuth 2.1 authorization server, you can configure your server to accept tokens from it:

```bash theme={null}
ezforge servers update my-server \
  --auth-mode byoa \
  --byoa-issuer https://auth.example.com \
  --byoa-jwks-uri https://auth.example.com/.well-known/jwks.json \
  --byoa-authorization-endpoint https://auth.example.com/oauth/authorize \
  --byoa-token-endpoint https://auth.example.com/oauth/token
```

ezForge performs a lightweight RFC 6750 structural Bearer-token check, then forwards the token to your MCP server for full JWT verification.

### OAuth scopes

| Scope            | Description                  |
| ---------------- | ---------------------------- |
| `mcp:read`       | List available tools         |
| `mcp:write`      | Call tools that modify state |
| `mcp:execute`    | Execute arbitrary tool calls |
| `offline_access` | Request refresh tokens       |

### Token lifetimes

| Token type    | Lifetime                 |
| ------------- | ------------------------ |
| Access token  | 15 minutes               |
| Refresh token | 30 days (rotated on use) |
| Auth code     | 10 minutes (single-use)  |