# 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](/http-api/openapi), 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:

```bash
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](/authentication/sessions-and-tokens#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                                                   |

```bash
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](/sign-in-setup/agent-access); every endpoint: [OAuth endpoints](/authentication/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.

```bash
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](/console/api-keys).

## Next steps

- [Make your first API call](/http-api/first-call) - a key and a session, end to end.
- [Base URLs, environments and CORS](/http-api/base-urls) - a key and a session belong to one environment.
- [HTTP API errors](/http-api/errors) - what a refused credential answers.
