The Sutra API lets scripts, integrations, and custom workflows work with the spaces you manage. A personal access token is the secret credential an integration sends with each API request. Create a separate named token for each integration so you can rotate or revoke it independently.
Before you start
Sutra API access is included automatically on Silver and Gold plans. You must be signed in to the Sutra account that will own the token. The token can only reach data and actions allowed by that account and by the token's access preset.
Create an API token
Click your avatar and open Settings.
Open Sutra API.
Click Create token and enter a clear name, such as "Reporting" or "MCP server."
Choose Read-only or Read & write.
Click Create token, then copy the token from the confirmation window.
Copy the token before you close the window. For security, Sutra shows the full token only once. Store it in your integration's secret or credential setting, not in page content, client-side code, a public repository, or a support message.
Choose the right access preset
Read-only
Use Read-only when the integration only needs to fetch information. It includes the available read scopes and cannot create or modify spaces, members, content, designs, or other Sutra records.
Read & write
Use Read & write only when the integration must create or change data. It includes read access plus the available write and action scopes. API-token authentication for the Sutra MCP server requires Read & write; for an interactive MCP connection, signing in with Sutra through OAuth is recommended instead.
The current Sutra API screen offers these two presets rather than individual scope checkboxes. The API still checks the specific scope required by every endpoint. A valid token returns 403 Forbidden when its preset does not include the needed scope or the owning account cannot manage the requested space.
Use the token
Send the token as a Bearer credential in the Authorization header. The current endpoint reference, request examples, IDs, pagination rules, and required scopes are at sutra.co/developers/docs.
Rotate or revoke a token
The Sutra API screen lists each token's name, prefix, status, and last-used date.
Rotate creates a replacement token and shows the new secret once. Update the integration immediately. The previous token has only a short transition window before it stops authenticating.
Revoke disables a token. Revoke it when an integration is retired or whenever you suspect the secret was exposed.
If you lose a token's full secret, it cannot be displayed again. Rotate it or create a replacement, update the integration, and revoke the old token.
Troubleshooting
Can't see Sutra API in Settings: confirm that the account is on Silver or Gold and that API access has not been suspended.
401 Unauthorized: the token is missing, mistyped, expired, rotated, or revoked. Copy the current replacement token into the integration and check its Authorization header.
403 Forbidden: the token is valid but is read-only for a write action, lacks the endpoint's required scope, or the owning account does not have access to that space.
429 Too Many Requests: the account reached an API rate or monthly usage limit. The Sutra API screen shows current usage and when the monthly allowance resets.