// DEVELOPERS/Getting started/Authentication

Authentication

ALLO supports two auth modes. API keys for server to server access. OAuth 2.0 with PKCE for end user flows where your app acts on behalf of a user.

API keys

One key per workspace. Pass it as a bearer token. Keys never expire but can be rotated or revoked from the dashboard.

// curlShell
curl https://api.allo.io/v1/projects \
  -H "Authorization: Bearer $ALLO_KEY"

Scopes

Every key and OAuth token carries a list of scopes. Request only what you need.

ScopeGrants
canvas:readList canvases, read blocks, read comments.
canvas:writeCreate and edit canvases and blocks.
project:readList projects, read members and statuses.
project:writeCreate projects, change status, invite members.
goal:readRead goals and progress.
goal:writeCreate goals and update progress.
webhook:manageCreate and rotate webhook endpoints.

OAuth 2.0 with PKCE

Use OAuth when an end user is authorizing your app to act on their behalf. PKCE is required for native and single page apps.

  1. Generate a code verifier and challenge.
  2. Send the user to /oauth/authorize with client_id, redirect_uri, scope, and code_challenge.
  3. On callback, exchange the code at /oauth/token with your code_verifier.
  4. Store the refresh_token. Refresh access tokens before they expire (1 hour).
// exchange.tsTypeScript
const res = await fetch("https://api.allo.io/oauth/token", {
  method: "POST",
  body: new URLSearchParams({
    grant_type: "authorization_code",
    code, code_verifier, client_id, redirect_uri
  })
})
// NOTE · Refresh tokens rotate
Each refresh returns a new refresh_token. Store the latest one and discard the old.