Need to manage API keys, view logs, or check usage?Open the Developer portal →

OAuth apps

Build an app that acts on another Circa user's behalf — with their explicit consent, scoped to the teams they choose.

An OAuth app is how you integrate with Circa when the data you need belongs to someone else. Instead of asking a customer to paste an API key into your product, you send them to Circa, they see a consent screen listing exactly what you are asking for, they pick which of their teams you may touch, and you receive tokens scoped to that decision.

API key or OAuth?

Circa has two authentication methods and they solve different problems.

API keyOAuth app
Acts as you, on your data.Acts on another Circa user's behalf, on their data.
One long-lived secret you create in the portal and put in your own environment.Short-lived access tokens issued per user, refreshed by your server.
Access is whatever the key owner can do on the teams they belong to.Access is the intersection of the scopes you requested and the teams the user picked.
x-api-key: circa_live_…Authorization: Bearer circa_oat_…
Internal scripts, your own backend, a data pipeline you own.A product with many Circa customers, a marketplace listing, an agent acting for a user.

If you are writing a script against your own Circa account, stop here and use an API key — it is one header and no round trip. If your product needs to read a customer's materials, keep reading.

The four actors

  • You, the developer — you register the app in the Developer portal and hold the client secret.
  • The app — identified by a circa_cid_… client id and authenticated with a circa_cs_… client secret. It has a fixed list of redirect URIs and a fixed list of scopes it may ever ask for.
  • The user — a Circa account holder who approves or denies your request on the consent screen. They can revoke you at any time from their profile.
  • The team — the tenant that actually owns the data. Materials, processes, credits and impact methods all live on a team, not on a user.

Every grant is per-team

This is the single most important difference between Circa and most OAuth providers. Circa is multi-tenant: a user typically belongs to several teams, and each team is a separate data boundary with its own library and its own credit balance. Approving your app does nothand you the user's whole account.

On the consent screen the user ticks which teams to include, exactly like granting a GitHub App access to specific organizations. The resulting grant stores that list, and every API call you make must name one team explicitly:

Authorization: Bearer circa_oat_9nQ2vJ0sYb4pR1tK7mLxD3fA6cHu8Zw5
x-team-id: 4b6f9c28-6f4e-4e7f-a36d-2ff989045d10

Circa checks two things on every request:

  • the team you named is in the grant — the user consented to it, and
  • the granting user is still an active member of that team today.

Both must hold. A token can never outlive the membership that authorized it, so if the user leaves a team, that team quietly drops out of your access while the same token keeps working for the others. Design for this — see Revoking access.

ℹ
Use GET /public/teams with teams:read to discover which team ids a token is actually good for, rather than storing a list you assume is still current.

How the flow runs

  1. You redirect the user to Circa's authorize screen with your client id, redirect URI, scopes and a state value.
  2. The user reviews the request, picks teams, and approves. Circa redirects back to you with a single-use authorization code that expires in 10 minutes.
  3. Your server exchanges that code at POST /public/oauth/token for an access token (circa_oat_…, 8 hours) and a refresh token (circa_ort_…, 60 days, rotating).
  4. You call the API with the access token plus x-team-id, and refresh before it expires.

Only the authorization_code and refresh_token grant types are supported. client_credentials is not offered — there is no way to act on a team without a human having consented.

⚠
The client secret and the token exchange belong on a server you control. Never ship circa_cs_… in a browser bundle, a mobile binary, or a public repo. Public clients that cannot hold a secret should use PKCE.

Where to go next