Authentication

Every connector, MCP, memory, and account-management request is resolved inside a user and organization boundary. Two pasted credential types are accepted across three header forms, plus a browser OAuth flow for interactive MCP clients:

Authenticate connector discovery

curl https://api.corespeed.io/connectors \
  -H "Authorization: Bearer $CORESPEED_API_KEY"

curl https://api.corespeed.io/connectors \
  -H "x-api-key: $CORESPEED_API_KEY"

The response is caller-specific: it includes visible connectors, connection status, account aliases, and whether this caller can remove an account.

Authenticate MCP

The same credentials work on the unified /mcp endpoint:

curl https://api.corespeed.io/mcp \
  -H "Authorization: Bearer $CORESPEED_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {"name": "my-agent", "version": "1.0.0"}
    }
  }'

Create, rotate, cap, and revoke agent keys in Dashboard → Keys.

MCP OAuth (browser sign-in)

Interactive MCP clients can authorize /mcp with no pasted key. An unauthenticated call returns a 401 whose WWW-Authenticate header advertises the RFC 9728 protected-resource metadata; the client discovers CoreSpeed's authorization server, runs OAuth 2.1 + PKCE in the browser, and retries /mcp with the issued token. The token is bound to the /mcp resource (RFC 8707). See MCP endpoint for the client config and the full flow.

Browser sign-in is live on api.corespeed.io; the API key and user session JWT above are the headless equivalents and work everywhere too.

Requests without a bearer credential

Three surfaces need no caller credential: the GET /health and GET /version probes, and the RFC 9728 protected-resource metadata document that browser sign-in discovers (GET /.well-known/oauth-protected-resource/mcp) — it has to be readable before you have a token. Artifact downloads use a short-lived signed URL instead of the headers above; do not strip or reuse its signature.

Error responses

Authentication failures use the nested error envelope:

{
  "error": {
    "type": "authentication_error",
    "message": "Authorization header or x-api-key is required",
    "code": "missing_authorization"
  }
}

missing_authorization fires when neither header is present, invalid_jwt when a bearer JWT fails verification, and invalid_api_key when a key is unknown, revoked, or expired. Billing and suspension states (402, 403) sit on top of a valid credential — a key that authenticates can still be refused.

Every status code and error code is listed once, in Errors & status codes. MCP tool failures can also arrive inside an HTTP 200 response with isError: true, so inspect the JSON-RPC result in addition to the HTTP status.