Skip to content
BuildBase
HTTP API menu

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-authSendUsed by
sessionx-session-id: <sessionId>Most of /api/v1/public: workspaces, billing, credits, notifications
sign-in-contextA state header (the hosted sign-in state id) or an org query parameter. Names the org; not a secretHosted sign-in steps under /api/v1/auth
login-tokenAuthorization: Bearer <login token> from hosted sign-in, plus state or orgThe few sign-in steps that need the person already signed in
none-at-routerNothing at the router. The route is public, or checks its own proof: a signature, a token in the bodyDiscovery documents, the token exchange, OAuth endpoints, public plan lists
org-credentialAuthorization: Bearer <orgId>:<secret> (an API key), or a console member's sessionThe organization API, /api/*
org-tokenAuthorization: Bearer <orgId>:<secret> only; a console session is refusedThe server API, /api/v1/server/*
company-keyAuthorization: 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 oneLifetime
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 keyexpiresIn 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 endCall
This sessionPOST /api/v1/public/logout with its x-session-id
Every session of the personPOST /api/v1/public/logout with body {"all": true}
One of the person's sessionsDELETE /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>:

DocumentWhat 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 tokenLifetime by default
An app client's180 days from issue; you can set 1 to 365 days, and an idle limit
An agent client'sRotates 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_expired on 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