Skip to main content
Every request includes Authorization: Bearer <credential>. Two kinds of credential are accepted.

API key

An API key is es_live_ followed by 32 hex characters. One can be created in the app under Settings, API keys, or with POST /api/v1/keys; an agent connected by OAuth can’t create keys. An agent that connects by link gets one when the user allows it (see Connect). The key is shown once, and only its hash is stored. A key works in one workspace the account owns, its default, and in any others ticked for it in Settings, API keys (or passed as workspace_ids when it is created); manage_settings changes the default between them. An account can have ten keys, GET /api/v1/keys lists the ones in the caller’s workspace, and DELETE /api/v1/keys/{keyId} revokes one.

OAuth token

An access token from the OAuth flow the MCP server advertises, or from the app’s own session. The token identifies the user. A connection made through the OAuth flow starts in the workspace chosen when the user connects, and can switch to the others the user allowed. Over REST, it can name another allowed workspace for one request with the x-workspace-id header, and any other is refused. The app’s own session can name any workspace the user can reach. GET /api/v1/workspaces lists every workspace the account can reach, with the caller’s role in each and whether the caller can act there. An app that acts for other users uses this method. Each user signs in through the authorization server named in the metadata at https://mcp.eversince.ai/.well-known/oauth-protected-resource, the app calls with that user’s token, and that user’s balances are charged. An API key acts for the account that created it and is charged to that account.

Script sessions

Over MCP, a script can get a credential without exposing a key. The get_api_session tool returns a single-use code, and POST /api/v1/sessions/redeem with { "code": "esx_…" } exchanges it for a bearer token that lasts 30 minutes in that connection’s workspace. The code is valid for 10 minutes and can be redeemed once. The redeem call itself needs no Authorization header. A session token can’t manage keys, webhook endpoints or the webhook signing secret.

Response headers

  • X-Request-Id: identifies the request for support.
  • Retry-After on a 429 and a 503: the seconds to wait before trying again.
A request without a valid credential gets a 401. A credential without access to the resource it names gets a 403.