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

# OAuth 2.1

> Authenticate MCP integrations using OAuth 2.1 with PKCE.

Zero supports OAuth 2.1 authorization code flow with PKCE for third-party integrations like ChatGPT, Claude, Claude Cowork, Codex, Claude Code, and Microsoft Copilot. OAuth lets external AI agents authenticate to the Zero MCP server on behalf of an organization.

The browser-facing authorization and consent screen is hosted at `zdlake.com`. Client registration, token exchange, revocation, and the MCP resource remain on `api.zdlake.com`.

## When to use OAuth vs API keys

| | API keys | OAuth 2.1 |
| - | - | - |
| **Use case** | Direct API access, scripts, CI/CD | Third-party MCP integrations |
| **Who creates credentials** | You, in the Zero dashboard | Automated through dynamic registration |
| **Token lifetime** | Long-lived, with optional rotation | One-hour access token and rotating refresh token |
| **Authentication** | `Authorization: Bearer sk_...` | `Authorization: Bearer oat_...` |

## Discovery

MCP clients discover Zero's OAuth configuration automatically through well-known metadata endpoints.

### Protected resource metadata

```http theme={null}
GET /.well-known/oauth-protected-resource/mcp
```

Returns:

```json theme={null}
{
  "resource": "https://api.zdlake.com/mcp",
  "authorization_servers": ["https://api.zdlake.com"],
  "scopes_supported": ["catalog:read"],
  "bearer_methods_supported": ["header"]
}
```

### Authorization server metadata

```http theme={null}
GET /.well-known/oauth-authorization-server
```

Returns:

```json theme={null}
{
  "issuer": "https://api.zdlake.com",
  "authorization_endpoint": "https://zdlake.com/oauth/authorize",
  "token_endpoint": "https://api.zdlake.com/oauth/token",
  "registration_endpoint": "https://api.zdlake.com/oauth/register",
  "revocation_endpoint": "https://api.zdlake.com/oauth/revoke",
  "scopes_supported": ["catalog:read"],
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "token_endpoint_auth_methods_supported": ["none"],
  "code_challenge_methods_supported": ["S256"],
  "resource_parameter_supported": true
}
```

### WWW-Authenticate header

Unauthenticated MCP requests return:

```http theme={null}
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://api.zdlake.com/.well-known/oauth-protected-resource/mcp", scope="catalog:read"
```

## Client registration

Zero supports dynamic client registration for public MCP clients.

```http theme={null}
POST /oauth/register
Content-Type: application/json
```

```json theme={null}
{
  "client_name": "Claude Code",
  "redirect_uris": ["http://127.0.0.1:49152/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}
```

Response:

```json theme={null}
{
  "client_id": "550e8400-e29b-41d4-a716-446655440000",
  "client_name": "Claude Code",
  "redirect_uris": ["http://127.0.0.1:49152/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}
```

Redirect URIs must use HTTPS or an HTTP loopback address. Zero matches redirect URIs exactly.

## Authorization code flow with PKCE

```text theme={null}
1. The MCP client discovers OAuth through the well-known endpoints
2. The client registers its callback URI
3. The client redirects you to the Zero consent screen
4. You sign in with Google, select an organization, and authorize security data access
5. Zero redirects to the registered callback with a single-use code
6. The client exchanges the code and PKCE verifier for tokens
7. The client uses the access token for MCP requests
8. The client rotates the refresh token when the access token expires
```

### Step 1: Authorization

```text theme={null}
https://zdlake.com/oauth/authorize
  ?response_type=code
  &client_id=550e8400-e29b-41d4-a716-446655440000
  &redirect_uri=http://127.0.0.1:49152/callback
  &scope=catalog:read
  &state=random_csrf_token
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256
  &resource=https://api.zdlake.com/mcp
```

The consent screen displays the client, requested access, and organizations available to your account. Approval redirects to the exact registered callback:

```http theme={null}
HTTP/1.1 302 Found
Location: http://127.0.0.1:49152/callback?code=oac_...&state=random_csrf_token
```

### Step 2: Token exchange

```http theme={null}
POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=oac_...
&redirect_uri=http://127.0.0.1:49152/callback
&client_id=550e8400-e29b-41d4-a716-446655440000
&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
&resource=https://api.zdlake.com/mcp
```

Response:

```json theme={null}
{
  "access_token": "oat_a1b2c3...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "ort_d4e5f6...",
  "scope": "catalog:read"
}
```

### Step 3: Use the access token

```bash theme={null}
curl "https://api.zdlake.com/mcp" \
  --header "Authorization: Bearer oat_a1b2c3..." \
  --header "Content-Type: application/json" \
  --header "Accept: application/json, text/event-stream" \
  --data '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":1}'
```

### Step 4: Refresh

```http theme={null}
POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=ort_d4e5f6...
&client_id=550e8400-e29b-41d4-a716-446655440000
&resource=https://api.zdlake.com/mcp
```

The response contains a new access and refresh token pair. The previous refresh token is revoked.

### Step 5: Revoke

```http theme={null}
POST /oauth/revoke
Content-Type: application/x-www-form-urlencoded

token=oat_a1b2c3...
```

Revocation returns `200 OK` even when the token was already revoked or is unknown.

## Scope

| Scope | Permissions |
| - | - |
| `catalog:read` | Search and retrieve normalized vulnerabilities, advisories, software, weaknesses, attack patterns, and provenance. |

## Data model

| Model | Purpose |
| - | - |
| OAuth client | Stores the public client identifier, display name, and exact redirect URIs. |
| Authorization code | Stores a single-use code hash, PKCE challenge, user, organization, scope, resource, redirect URI, and expiration. |
| OAuth token | Stores access and refresh token hashes with their client, user, organization, scope, resource, expiration, and revocation state. |

## Platform compatibility

| | ChatGPT | Claude and Cowork | Codex | Claude Code | Microsoft Copilot |
| - | - | - | - | - | - |
| Registration | Dynamic registration | Dynamic registration | Dynamic registration or configured client ID | Dynamic registration or configured client ID | Dynamic discovery |
| PKCE | Required, S256 | Required, S256 | Required, S256 | Required, S256 | Required when acting as a public client |
| Resource binding | `https://api.zdlake.com/mcp` | `https://api.zdlake.com/mcp` | `https://api.zdlake.com/mcp` | `https://api.zdlake.com/mcp` | `https://api.zdlake.com/mcp` |

## Security

* Access, refresh, and authorization codes are stored as SHA-256 hashes, never plaintext.
* Access tokens expire after one hour.
* Refresh tokens expire after 30 days and rotate on use.
* PKCE S256 is required for every authorization request.
* Authorization codes expire after 10 minutes and can be consumed once.
* Tokens are bound to one client, user, organization, scope, and MCP resource.
* MCP access tokens are validated at the MCP boundary and are not forwarded to the REST API.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.