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.

Pass via header (recommended):

Header Auth

Authorization: Bearer sk_live_abc123def456...

Or query parameter:

Query Parameter

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

Get your API key

Get your API key from the Account dashboard. Header authentication is recommended for security.

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:

Auth Error

{
  "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:

OAuth Discovery

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

Discovery Response

{
  "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:

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

Client Registration

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

Token Exchange

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

Token Response

{
  "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.

Client Credentials Request

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

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

Simple exchange

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:

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

Next Steps

Error Handling

Understand error responses and build resilient integrations.