Authentication

Scopes

Scopes are a coarse resource:action split (read, write, sometimes delete) per resource. The same vocabulary applies to PATs and to OAuth apps, so a token or an app only ever gets what you check. Grant the least you need.

What a token can and cannot do

A personal access token or an OAuth access token acts as the person who created it. It is subject to that person's role, module permissions, and plan, exactly as they are when signed in, and scopes only narrow it further. When the person is removed from the workspace or their access is disabled, every token they created stops working on the next request. The workspace IP allowlist applies to tokens as well as to signed-in sessions, in addition to any allowlist set on the token itself.

An operation accepts a token only when it declares the scope it requires. A few operations are never available to a token, whatever scopes it holds:

• Create or rotate an access token. Listing and revoking tokens remain available.
• Sign in, sign out, manage sessions, and two-factor authentication.
• Approve an OAuth application or register one.
• Delete or export an account.
• Configure single sign-on, SCIM, or the workspace IP allowlist.
• Change the plan or pay for it.
• Super administration.

Sensitive areas

Four areas hold a workspace's most sensitive records, so tokens cannot use their scopes until a workspace owner or administrator allows the area in Settings, then API access, under Sensitive areas. The setting is checked on every request, so allowing or withdrawing an area applies to every token at once, and each change is recorded in the audit log.

When a token is refused, the response is a 403 problem, and its type field says why:

1. Register an app

Open Settings, then Developer and click Register OAuth app. Provide a name, one or more redirect URIs (exact-match HTTPS callbacks), and the scopes the app may request. Choose the client type:

2. Discover the endpoints

Atlas publishes two RFC discovery documents. The first (RFC 8414) tells a client where the authorization server lives; the second (RFC 9728) tells an MCP client which authorization server protects the hosted /mcp resource.

curl https://api-atlas.wrxstack.com/.well-known/oauth-authorization-server

{
  "issuer": "https://api-atlas.wrxstack.com",
  "authorization_endpoint": "https://atlas.wrxstack.com/oauth/authorize",
  "token_endpoint": "https://api-atlas.wrxstack.com/v2/oauth/token",
  "userinfo_endpoint": "https://api-atlas.wrxstack.com/v2/oauth/userinfo",
  "jwks_uri": "https://api-atlas.wrxstack.com/.well-known/jwks.json",
  "registration_endpoint": "https://api-atlas.wrxstack.com/v2/oauth/register",
  "revocation_endpoint": "https://api-atlas.wrxstack.com/v2/oauth/revoke",
  "introspection_endpoint": "https://api-atlas.wrxstack.com/v2/oauth/introspect",
  "device_authorization_endpoint": "https://api-atlas.wrxstack.com/v2/oauth/device_authorization",
  "scopes_supported": ["tasks:read", "tasks:write", "projects:read", "..."],
  "response_types_supported": ["code"],
  "grant_types_supported": [
    "authorization_code",
    "refresh_token",
    "urn:ietf:params:oauth:grant-type:device_code"
  ],
  "token_endpoint_auth_methods_supported": ["none", "client_secret_post"],
  "code_challenge_methods_supported": ["S256"],
  "subject_types_supported": ["public"],
  "id_token_signing_alg_values_supported": ["RS256"]
}

The protected-resource document points MCP clients at the authorization server that guards the hosted /mcp endpoint:

curl https://api-atlas.wrxstack.com/.well-known/oauth-protected-resource

{
  "resource": "https://api-atlas.wrxstack.com/mcp",
  "authorization_servers": ["https://api-atlas.wrxstack.com"],
  "scopes_supported": ["tasks:read", "tasks:write", "..."],
  "bearer_methods_supported": ["header"],
  "resource_name": "Atlas MCP",
  "resource_documentation": "https://atlas.wrxstack.com/docs/mcp"
}

3. Authorization code flow (with PKCE)

This is the flow for apps a user signs in to. PKCE (Proof Key for Code Exchange, S256) is required for public clients and recommended for everyone: it stops a stolen authorization code from being redeemed by anyone but you.

4. Call the API

The access token is an opaque bearer token. Send it exactly like a PAT: the /v1 API does not care which credential type it is.

curl -H "Authorization: Bearer at_9f8e7d6c5b4a..." \
  https://api-atlas.wrxstack.com/v1/tasks?limit=50

5. Refresh before it expires

Access tokens live one hour. When yours nears expiry (or a call returns 401), exchange the refresh token for a new pair. Refresh tokens rotate: each refresh returns a brand-new refresh token and invalidates the one you sent. Store the new one.

curl -X POST https://api-atlas.wrxstack.com/v2/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "refresh_token",
    "refresh_token": "rt_0a1b2c3d4e5f...",
    "client_id": "cli_YOUR_CLIENT_ID",
    "client_secret": "cs_YOUR_CLIENT_SECRET"
  }'

Introspect a token

A resource server can ask Atlas whether a token is still active and what it carries (RFC 7662). An inactive token returns { "active": false } and nothing else.

curl -X POST https://api-atlas.wrxstack.com/v2/oauth/introspect \
  -H "Content-Type: application/json" \
  -d '{
    "token": "at_9f8e7d6c5b4a...",
    "client_id": "cli_YOUR_CLIENT_ID",
    "client_secret": "cs_YOUR_CLIENT_SECRET"
  }'

{
  "active": true,
  "scope": "tasks:read tasks:write",
  "client_id": "cli_YOUR_CLIENT_ID",
  "token_type": "Bearer",
  "sub": "usr_01HW3RA2B3C4D5E6F7G8H9J0K1",
  "aud": "https://api-atlas.wrxstack.com/mcp",
  "exp": 1746123456,
  "iat": 1746119856,
  "jti": "jti_7c9e2f14..."
}

Revoke a token

Revoke an access or refresh token (RFC 7009) at logout or when a user disconnects your app. Revoking a refresh token also revokes the access tokens minted from it.

curl -X POST https://api-atlas.wrxstack.com/v2/oauth/revoke \
  -H "Content-Type: application/json" \
  -d '{
    "token": "rt_0a1b2c3d4e5f...",
    "token_type_hint": "refresh_token",
    "client_id": "cli_YOUR_CLIENT_ID",
    "client_secret": "cs_YOUR_CLIENT_SECRET"
  }'

Device code flow

For input-constrained devices (a CLI, a TV, an IoT box) that cannot host a browser redirect, use the device-code grant (RFC 8628). Start it, show the user the user_code and verification_uri, then poll the token endpoint until they approve.

curl -X POST https://api-atlas.wrxstack.com/v2/oauth/device_authorization \
  -H "Content-Type: application/json" \
  -d '{ "client_id": "cli_YOUR_CLIENT_ID", "scope": "tasks:read" }'

{
  "device_code": "dc_1a2b3c...",
  "user_code": "WDJB-MJHT",
  "verification_uri": "https://atlas.wrxstack.com/device",
  "verification_uri_complete": "https://atlas.wrxstack.com/device?user_code=WDJB-MJHT",
  "expires_in": 600,
  "interval": 5
}

Poll every interval seconds. Until the user approves you get authorization_pending; once they do, the same call returns the token pair.

curl -X POST https://api-atlas.wrxstack.com/v2/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
    "device_code": "dc_1a2b3c...",
    "client_id": "cli_YOUR_CLIENT_ID"
  }'