OAuth 2.0

Let users connect your app to their Atlas account. You get an access token limited to the scopes they approve, so your app can read their boards or manage todos on their behalf. Atlas implements the authorization code flow with PKCE (S256), refresh token rotation and token revocation.

Flow

Authorization code + PKCE (S256). Public and confidential clients.

Token lifetimes

Access tokens 1 hour. Refresh tokens 30 days, rotated on use.

Board limits

Users can restrict your app to chosen boards, with per-board scopes.

Endpoints

GET
/oauth/authorize

Authorisation endpoint (user-facing consent screen)

POST
/api/oauth/token

Exchange a code or refresh token for tokens

POST
/api/oauth/revoke

Revoke an access or refresh token

GET
/api/oauth/userinfo

Profile of the authorising user (identify scope)

GET
/.well-known/oauth-authorization-server

Server metadata (RFC 8414)

Discovery document: /.well-known/oauth-authorization-server

1Register an application

Create one on the applications page. You'll get a client ID and, for confidential clients, a secret that is shown once. Redirect URIs must match exactly. Use a public client (no secret) for single page apps, mobile apps and CLIs. Public clients must use PKCE.

2Send the user to authorize

https://atlas.s8n.xyz/oauth/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https%3A%2F%2Fexample.com%2Fcallback
  &scope=identify%20boards%3Aread%20todos%3Awrite
  &state=RANDOM_STRING
  &code_challenge=BASE64URL(SHA256(code_verifier))
  &code_challenge_method=S256

The user signs in with Discord if needed and sees what your app asks for. They can also limit your app to specific boards, with separate permissions per board (within the scopes you requested); you only ever see the boards they chose. On approval they're redirected to redirect_uri?code=…&state=…. If they decline you get error=access_denied. Always verify state.

3Exchange the code

curl -X POST https://atlas.s8n.xyz/api/oauth/token   -d grant_type=authorization_code   -d code=AUTH_CODE   -d redirect_uri=https://example.com/callback   -d client_id=YOUR_CLIENT_ID   -d code_verifier=ORIGINAL_VERIFIER   -d client_secret=YOUR_SECRET   # confidential clients only

Response

{
  "access_token": "oat_…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "ort_…",
  "scope": "identify boards:read todos:write todos:update"
}

Client credentials may also be sent with HTTP Basic auth. JSON bodies are accepted too.

4Call the API

curl https://atlas.s8n.xyz/api/v1/boards -H "Authorization: Bearer oat_…"

Access tokens last 1 hour. Refresh tokens last 30 days and are rotated: each refresh returns a new refresh token and invalidates the previous one. An old refresh token is rejected with invalid_grant.

curl -X POST https://atlas.s8n.xyz/api/oauth/token   -d grant_type=refresh_token -d refresh_token=ort_… -d client_id=YOUR_CLIENT_ID

Revoke with POST /api/oauth/revoke (token=…&client_id=…). Users can also disconnect apps from Settings at any time.

Scopes

identifyRead your basic profile (id, username, avatar)
boards:readRead your boards, categories and tags
boards:writeCreate boards, categories and tags
boards:updateEdit and reorder boards, categories and tags
boards:deleteDelete boards, categories and tags
todos:readRead todos and the todo history
todos:writeCreate todos
todos:updateEdit, move, complete, scrap and restore todos
todos:deleteDelete todos (to History), delete them permanently and empty History
data:exportExport your boards and todos
data:importImport boards and todos

Requests for a scope your app isn't registered for are rejected. Management endpoints such as API keys and apps are never available to OAuth tokens.

Errors

Token endpoint errors follow RFC 6749: { "error": "invalid_grant", "error_description": "…" }. Common values: invalid_request, invalid_client, invalid_grant, invalid_scope, unsupported_grant_type. API errors after authorization use the codes below.

401unauthorizedMissing, invalid, expired or revoked credential
403forbidden / insufficient_scopeThe credential lacks the scope or the action is website-only
429rate_limitedToo many requests – see Retry-After

Try the flow

Run the full authorization code + PKCE flow against this server, right here.

1Pick your app and scopes

Must exactly match one of the app's registered redirect URIs.

2Exchange the code for tokens

After approving you're sent back here with ?code=…. The code is single use and expires in 10 minutes.

3Call the API

Complete step 2 first.