Authentication

Prerequisites

API access is included automatically on Silver and Gold accounts.

API Tokens And MCP OAuth

For direct REST API calls, use a dedicated Sutra API token in the Authorization header:

Authorization: Bearer sutra_live_sk_<prefix>_<secret>

For MCP clients, OAuth is supported and recommended. The Sutra MCP server runs an OAuth 2.1 Authorization Code flow with PKCE, opens Sutra login and consent in your browser, then caches and refreshes its credentials locally. You normally do not need to create or paste an API token for MCP setup. See mcp-server.md.

The MCP server still sends standard Authorization: Bearer ... requests to the Admin API after OAuth completes. Use a manually created API token instead when you are running the MCP server in a headless/server environment where browser login is not practical.

Getting Your Token

Log in to your Sutra account.
Go to Settings → Sutra API in your account settings.
Click Create Token to generate a new API token.
Copy the token immediately — it is only shown once and cannot be retrieved later.

If you don't see the API section in your settings, confirm that your account is on Silver or Gold. Contact support@sutra.co for assistance if you are on a qualifying plan and the section is still missing.

Token Storage

Tokens are opaque credentials. Sutra stores only the token prefix and an HMAC-SHA256 digest keyed with API_TOKEN_PEPPER; plaintext tokens are shown only when created or rotated.

The V1 API does not expose self-service token or application-management endpoints.

An API token acts as a Sutra user. The user is the token creator when one is recorded, otherwise the API application owner. By default, access includes every space this user can manage — including archived spaces (so archiving is reversible through the API) and pending spaces (scheduled to launch). Sutra can optionally restrict a token to specific spaces, but that restriction is only a security limit on the token. Tokens do not have a single root space in Sutra's product model.

Rules:

Do not send API tokens in query parameters. auth_token, api_token, and token query parameters are rejected.
Cookies, app session bearer tokens, and legacy mobile tokens do not authenticate /api/admin/v1.
Rotated tokens remain valid only during their grace period.
Expired, revoked, suspended, or grace-expired rotated tokens return 401.