# Authentication

> Markdown variant of <https://www.skillzdrive.com/docs/guides/authentication>.

API keys, OAuth 2.0, and securing your integration.

## API key authentication

Keys follow the format `sk_live_` + random string. This is the
simplest and most common method. Get keys from
<https://www.skillzdrive.com/dashboard/get-setup>.

### Pass via header (recommended)

```http
Authorization: Bearer sk_live_abc123def456...
```

### Or query parameter

```http
GET /api/mcp?apiKey=sk_live_abc123def456...
```

Header authentication is recommended for security — query
parameters can leak into logs and HTTP referrer headers.

## Key constraints

Each API key has properties that control access:

| Property | Description |
|----------|-------------|
| `enabled` | Must be `true` for the key to work |
| `expires_at` | Optional expiration date |
| `monthly_execution_quota` | Max script executions per month (0 = unlimited) |
| `current_month_usage` | Counter, resets monthly |
| `rate_limit_per_minute` | Max requests per minute |
| `allowed_skill_ids` | Optional whitelist of accessible skills (null = all) |

### Skill access resolution

Your API key's `allowed_skill_ids` intersects with the union of your
personal drive, team drives, and shared skills. If
`allowed_skill_ids` is null (all skills), you get access to the full
union. If it's a specific list, only skills in both the list and
the union are accessible.

## Error responses

When authentication fails, the server returns structured errors:

```json
{
  "error": "access_denied",
  "message": "API key required",
  "suggestions": ["Get an API key at https://www.skillzdrive.com/dashboard"]
}
```

## OAuth 2.0

For AI clients that require OAuth (Claude.ai, Claude Code, etc.),
the server implements full OAuth 2.0.

### Discovery endpoint

```http
GET /.well-known/oauth-authorization-server
```

Response:

```json
{
  "issuer": "https://www.skillzdrive.com",
  "authorization_endpoint": "https://www.skillzdrive.com/authorize",
  "token_endpoint": "https://www.skillzdrive.com/api/mcp/oauth/token",
  "registration_endpoint": "https://www.skillzdrive.com/api/mcp/oauth/register",
  "grant_types_supported": ["authorization_code", "client_credentials"],
  "code_challenge_methods_supported": ["S256", "plain"],
  "scopes_supported": ["skills:read", "skills:execute"]
}
```

### Authorization Code + PKCE

Used by Claude Code and other MCP clients that perform the full
OAuth dance.

Flow:

1. Client calls `POST /oauth/register` (Dynamic Client Registration).
2. Client redirects user to authorization endpoint with PKCE challenge.
3. User authorizes → redirect back with `code`.
4. Client exchanges `code` + `code_verifier` at `POST /oauth/token`.
5. Server returns API key as `access_token`.

Client registration body:

```json
{
  "redirect_uris": ["http://localhost:3000/callback"],
  "client_name": "My MCP App",
  "grant_types": ["authorization_code"],
  "token_endpoint_auth_method": "none"
}
```

Token exchange body:

```json
{
  "grant_type": "authorization_code",
  "code": "AUTH_CODE",
  "code_verifier": "VERIFIER",
  "redirect_uri": "http://localhost:3000/callback"
}
```

Token response:

```json
{
  "access_token": "sk_live_...",
  "token_type": "Bearer",
  "expires_in": 86400,
  "scope": "skills:read skills:execute"
}
```

### Client Credentials

Simple API key exchange for programmatic access without user
interaction.

```http
POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=my-app&client_secret=sk_live_YOUR_KEY
```

Client credentials is the simplest OAuth flow — your API key is
both the secret and the resulting access token.

### API key resolution priority

When using OAuth, the server resolves the API key in this order:

1. API key linked during the authorization flow.
2. Bearer token on the token exchange request.
3. API key captured during client registration.

## Next steps

- [Connecting](https://www.skillzdrive.com/docs/guides/connecting.md): configure your MCP client to connect to SkillzDrive.
- [Security](https://www.skillzdrive.com/docs/security.md): best practices for securing API keys and integrations.
- [MCP tools reference](https://www.skillzdrive.com/docs/reference/tools.md): error response shape and full tool reference.