Authorization code flow

Circa implements the standard OAuth 2.0 authorization code grant, with one Circa-specific twist: the user picks which teams to grant, and every subsequent API call must name one of them with an x-team-id header. The four steps below are the whole integration.

1. redirect  →  https://app.circa.ai/oauth/authorize?client_id=…
2. consent   →  user picks teams, approves
3. callback  →  https://your.app/callback?code=circa_code_…&state=…
4. exchange  →  POST https://api.circa.ai/public/oauth/token
5. call      →  Authorization: Bearer circa_oat_…  +  x-team-id: …

Step 1 — Redirect the user to Circa

Build an authorize URL and send the user's browser to it (a full navigation or a popup — not an iframe, and not a server-side fetch).

https://app.circa.ai/oauth/authorize
  ?client_id=circa_cid_Vb3nT7yQ0sKp2mLxD9fA6cHu
  &redirect_uri=https%3A%2F%2Fapp.example.com%2Fintegrations%2Fcirca%2Fcallback
  &response_type=code
  &scope=profile%3Aread%20teams%3Aread%20materials%3Aread
  &state=f8Kd2p9QzR1a

Query parameters

Adding PKCE

PKCE binds the authorization code to the client that started the flow, so a stolen code is useless on its own. Generate a random code_verifier, derive the challenge, send the challenge in step 1, and send the verifier in step 3.

PKCE is opt-in: Circa requires a code_verifier at the token endpoint only when the authorization request carried a code_challenge. If you did not send one, omitting the verifier is fine — but then the code is protected by your client secret alone. Both S256 and plain are accepted; plain exists for constrained clients and offers no protection against a challenge that leaks alongside the code, so use S256.

import crypto from "node:crypto";

const codeVerifier = crypto.randomBytes(32).toString("base64url");
const codeChallenge = crypto
  .createHash("sha256")
  .update(codeVerifier)
  .digest("base64url");

const state = crypto.randomBytes(16).toString("base64url");
// Persist { state, codeVerifier } against this user's session.

const url = new URL("https://app.circa.ai/oauth/authorize");
url.searchParams.set("client_id", process.env.CIRCA_CLIENT_ID);
url.searchParams.set("redirect_uri", process.env.CIRCA_REDIRECT_URI);
url.searchParams.set("response_type", "code");
url.searchParams.set("scope", "profile:read teams:read materials:read");
url.searchParams.set("state", state);
url.searchParams.set("code_challenge", codeChallenge);
url.searchParams.set("code_challenge_method", "S256");

res.redirect(url.toString());

Step 2 — The user consents and picks teams

Circa shows a consent screen with your app's logo and name, the list of scopes you asked for in plain language, and a selector listing every team the user is an active member of. They tick the teams you may access. Credit-spending scopes (materials:pull, processes:pull) are called out separately, because approving them lets you debit the selected teams' credit balances.

If the user is logged out, they are sent through sign-in first and returned to the consent screen. If your app has not been reviewed, the screen carries an unverified warning.

On approval

Circa redirects the browser to your registered redirect_uri with a single-use code and your state:

https://app.example.com/integrations/circa/callback
  ?code=circa_code_7yQ0sKp2mLxD9fA6cHu8Zw5nT3vJb1R4
  &state=f8Kd2p9QzR1a

On denial

If the user clicks cancel you get an error back on the same redirect URI, still carrying your state. Treat it as a normal outcome, not a failure — show the user a way to try again.

https://app.example.com/integrations/circa/callback
  ?error=access_denied
  &error_description=The%20user%20denied%20the%20authorization%20request.
  &state=f8Kd2p9QzR1a

Step 3 — Exchange the code for tokens

This call happens server to server, never from the browser. The body is application/x-www-form-urlencoded; application/json is accepted too, with the same field names.

Two ways to authenticate your app

Pick one. HTTP Basic keeps the secret out of the request body (and out of anything that logs bodies), so prefer it if your HTTP client makes it easy; the body form is simpler to hand-roll.

curl -s -X POST 'https://api.circa.ai/public/oauth/token' \
  -u "$CIRCA_CLIENT_ID:$CIRCA_CLIENT_SECRET" \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=authorization_code' \
  -d 'code=circa_code_7yQ0sKp2mLxD9fA6cHu8Zw5nT3vJb1R4' \
  -d 'redirect_uri=https://app.example.com/integrations/circa/callback' \
  -d 'code_verifier=YOUR_CODE_VERIFIER'

Success response

{
  "access_token": "circa_oat_9nQ2vJ0sYb4pR1tK7mLxD3fA6cHu8Zw5",
  "token_type": "Bearer",
  "expires_in": 28800,
  "refresh_token": "circa_ort_3fA6cHu8Zw5nQ2vJ0sYb4pR1tK7mLxD",
  "scope": "profile:read teams:read materials:read"
}

• expires_in is seconds — 28800 is 8 hours. Store an absolute expiry, not a countdown.
• scope is what you actually got. Read it rather than assuming you received everything you asked for.
• refresh_token is valid for 60 days and rotates on every use — see Refreshing tokens.
• Both tokens are opaque and stored hashed. Do not try to parse them; the only thing the value tells you is which kind it is, from its prefix.

Error responses

Every failure at the token endpoint comes back in the standard OAuth shape — a JSON body with an error code and a human-readable error_description, never Circa's usual { statusCode, message } envelope. Branch on error; the description is for your logs, not your control flow.

The status code is 401 for invalid_client (with a WWW-Authenticate: Basic realm="circa" header), 500 for server_error, and 400 for everything else.

{
  "error": "invalid_grant",
  "error_description": "The authorization code has expired."
}

{
  "error": "invalid_client",
  "error_description": "Client authentication failed."
}

Failures before the consent screen

Step 1 is a browser navigation, so its failures never reach your server directly — the consent page renders an error instead of redirecting, which is deliberate: an unknown client_id or an unregistered redirect_urimust not be turned into an open redirect. The page's backing request answers in Circa's Nest-style shape, { error, message } — note message, not error_description; the OAuth2 body is used at the token endpoint only.

{
  "error": "invalid_scope",
  "statusCode": 400,
  "message": "This application is not registered for scope(s): materials:pull."
}

Step 4 — Call the API

Send the access token as a bearer token, and name the team you are acting on:

curl -s 'https://api.circa.ai/public/materials?search=polyethylene&limit=10' \
  -H 'Authorization: Bearer circa_oat_9nQ2vJ0sYb4pR1tK7mLxD3fA6cHu8Zw5' \
  -H 'x-team-id: 4b6f9c28-6f4e-4e7f-a36d-2ff989045d10' \
  -H 'Circa-Version: 2026-05-11.arrakis'

Errors on an OAuth-authenticated call

These are ordinary public-API responses, not OAuth protocol responses, so they use the normal { statusCode, message } envelope — with an error discriminator on the two that have one.

{
  "statusCode": 400,
  "message": "Missing required 'x-team-id' header. Pass the id of a team this authorization covers."
}

{
  "statusCode": 403,
  "message": "'Acme LCA' was not granted access to team '4b6f9c28-6f4e-4e7f-a36d-2ff989045d10'."
}

{
  "statusCode": 403,
  "message": "The user who authorized 'Acme LCA' is no longer a member of team '4b6f9c28-6f4e-4e7f-a36d-2ff989045d10'."
}

{
  "error": "invalid_token",
  "statusCode": 401,
  "message": "The access token has expired."
}

The 401 message tells you which case you hit — the access token is invalid, has expired, or has been revoked; the authorization behind it has been revoked; or the application has been suspended. Missing a scope is a 403 with error: "insufficient_scope", described under Scopes.

What to persist

Per authorized user, your database wants: the access token and its absolute expiry, the newest refresh token, the granted scope string, and the team ids you discovered. Refresh ahead of expiry rather than waiting for a 401, and re-read the team list periodically — the set can shrink underneath you without any error being reported until you call.