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

# Authentication

> API keys, OAuth tokens and script sessions, and how each is bound to a workspace.

Every request carries `Authorization: Bearer <credential>`. Two kinds of credential are accepted.

## API key

An API key is `es_live_` followed by 32 hex characters. Create one in the app under Settings, API keys, or with `POST /api/v1/keys`. The key is shown once, and only its hash is stored. A key is bound to one workspace the account owns and works there only. An account can hold ten keys, `GET /api/v1/keys` lists them, 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, and a connection made with it is scoped to one workspace when the user connects. Over REST, the same token can name another workspace the user can reach, for one request, with the `x-workspace-id` header. `GET /api/v1/workspaces` lists those workspaces with the caller's role in each.

An app that acts for other users takes this path. 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 pay. An API key acts for the account that created it and pays from that account.

## Script sessions

Connected over MCP, you can give a script 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 takes no Authorization header. A session token cannot create, list or revoke keys, or read or change the webhook signing secret.

## Response headers

* `X-Request-Id`: quote it when writing to support.
* `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`, plus `Retry-After` on a 429 and a 503.

A request with no valid credential receives a 401. A credential without access to the resource it names receives a 403.