Authenticate API requests
Every credential the BuildBase HTTP API accepts - end-user sessions, OAuth 2.0 for agents, organization API keys - with lifetimes and how to revoke each.
In short
BuildBase needs to know who is asking before it answers. There are three kinds of credential:
- A session says "I am this signed-in user of your app". Your app's frontend and backend send it.
- An organization API key says "I am your company's server". Only your servers hold it.
- OAuth 2.0 lets an AI agent or another company's app ask one of your users for permission, the way "Sign in with Google" asks you.
Each operation's reference page, and the x-auth field of the OpenAPI spec, says which one it takes.
Which credential each route takes
x-auth | Send | Used by |
|---|---|---|
session | x-session-id: <sessionId> | Most of /api/v1/public: workspaces, billing, credits, notifications |
sign-in-context | A state header (the hosted sign-in state id) or an org query parameter. Names the org; not a secret | Hosted sign-in steps under /api/v1/auth |
login-token | Authorization: Bearer <login token> from hosted sign-in, plus state or org | The few sign-in steps that need the person already signed in |
none-at-router | Nothing at the router. The route is public, or checks its own proof: a signature, a token in the body | Discovery documents, the token exchange, OAuth endpoints, public plan lists |
org-credential | Authorization: Bearer <orgId>:<secret> (an API key), or a console member's session | The organization API, /api/* |
org-token | Authorization: Bearer <orgId>:<secret> only; a console session is refused | The server API, /api/v1/server/* |
company-key | Authorization: Bearer bbck_... or bbct_... | The company API, /api/v1/company/*, for one enterprise customer's IT team |
Sessions: the app API
A session id is a long random string. The SDK keeps it after a person signs in, and sends it as x-session-id on every app API call. Your backend reads it from your own cookie or header and sends it on:
curl -s "https://api.console.buildbase.app/api/v1/public/session" \
-H "x-session-id: $BUILDBASE_SESSION_ID"| Way to get one | Lifetime |
|---|---|
| A person signs in (hosted sign-in, the SDK) | 30 days by default, set per session, capped at 180 days |
POST /api/v1/public/token/exchange with a key | expiresIn seconds, 60 up to 30 days; 30 days when unset |
The token exchange swaps an organization API key for a session, for the key's own user or, with an owner or admin key, for a user you name with userId. Its body, refusals and audit trail are in Opening a session as one of your users.
Revoke a session:
| To end | Call |
|---|---|
| This session | POST /api/v1/public/logout with its x-session-id |
| Every session of the person | POST /api/v1/public/logout with body {"all": true} |
| One of the person's sessions | DELETE /api/v1/public/sessions/{id}, id from GET /api/v1/public/sessions |
A revoked or expired session answers 401.
OAuth 2.0: agents and third-party apps
Every BuildBase app is an OAuth 2.0 authorization server. An AI agent or another company's app finds it, asks one of your users to approve it on a consent screen, and receives a token. Your own server makes that token (the Application token URL in your agent access settings), and the agent then calls your app or your MCP server with it, not BuildBase's routes.
Discovery, for an org id <orgId>:
| Document | What it is |
|---|---|
GET /.well-known/oauth-authorization-server/org/<orgId> | RFC 8414 authorization server metadata: every endpoint below |
GET /org/<orgId> | The issuer |
curl -s "https://api.console.buildbase.app/.well-known/oauth-authorization-server/org/$BUILDBASE_ORG_ID"The metadata lists authorization_endpoint, token_endpoint, revocation_endpoint, introspection_endpoint and device_authorization_endpoint under /api/v1/auth/oauth2, each with ?org=<orgId>, and registration_endpoint only while agents may register themselves. The response type is code, with PKCE S256.
Access tokens are your server's: their lifetime is what your Application token URL says. BuildBase keeps the refresh tokens:
| Refresh token | Lifetime by default |
|---|---|
| An app client's | 180 days from issue; you can set 1 to 365 days, and an idle limit |
| An agent client's | Rotates on every use and lapses after 30 days unused; you can set the idle limit and a maximum |
Revoke one with POST /api/v1/auth/oauth2/revoke?org=<orgId> (RFC 7009). A person removes an agent they approved from the connected agents list in your app (useConnectedAgents()). Setup: Set up agent and app access; every endpoint: OAuth endpoints.
Organization API keys
An API key is <orgId>:<secret>. Send it as Authorization: Bearer <orgId>:<secret>; the Bearer word is optional, since a value with a colon is read as a key.
curl -s "https://api.console.buildbase.app/api/blogs" \
-H "Authorization: Bearer $BUILDBASE_API_TOKEN"- Where: the console, Settings > API keys, Create API key. The whole key is shown once.
- What it may do: a key has no scopes. It holds a role: an API role you make under Settings > API roles, such as content-reader, or, left empty, the role of the person who made it. A key can never hold more access than its maker. An App-server key can never change plans, add-ons, coupons, organization settings or the blueprint; an Admin key can.
- Lifetime: until its optional Expires at, which your plan may cap. An expired key answers
401(token_expiredon the token exchange). - Revoke: Deactivate on its row cuts access at once. Replace a key with no gap by creating the new one, deploying it, then deactivating the old one.
Never put a key in browser code, a mobile app or a chat with an AI tool. Step by step, with screenshots: Make an API key for your server.
Next steps
- Make your first API call - a key and a session, end to end.
- Base URLs, environments and CORS - a key and a session belong to one environment.
- HTTP API errors - what a refused credential answers.