Authentication

Every request needs a token in the Authorization header:

The token can be an API key or an OAuth access token. API keys work with both the REST API and MCP. An OAuth access token works only with the address it was requested for.

Send requests to the same domain where you created the key or connected the app.

API keys

Use an API key for your own scripts and server integrations. Organization admins create keys in Admin → API.

A key can expire after 7, 30, 90 or 365 days, on a date you choose, or never. The full key is shown only once, so store it somewhere safe.

OAuth

OAuth lets an app act for a signed-in member without an API key. AI tools that connect through MCP use OAuth, and you can use it in your own app too.

The app sends the member to your organization’s sign-in page, where they approve the access the app asks for. Ask only for the scopes your app needs. An app that asks for no scopes gets organization:read only.

To use OAuth in your own app:

Register your app at https://<organization-domain>/api/oauth/register to get a client_id, or use the URL of your app’s client metadata document as its client_id. No client secret is needed.
Use the authorization code flow with PKCE (S256). The authorization URL is https://<organization-domain>/oauth/authorize and the token URL is https://<organization-domain>/api/oauth/token.
Send resource with the address the token is for: https://<organization-domain>/api/v1 for the REST API or https://<organization-domain>/api/mcp for MCP.

Access tokens expire after 30 minutes. Use the refresh token to get a new one. Each refresh token works once and expires after 90 days without use.