# OAuth endpoints

The OAuth 2.0 endpoints for client registration (RFC 7591 and 7592), token introspection (RFC 7662) and token revocation (RFC 7009).

Every BuildBase app is an OAuth 2.0 authorization server. This page is the reference for the endpoints an agent or a third-party app calls around a token: registering a client, managing that registration, checking a token and revoking it. The sign-in flow itself (authorize, token, PKCE, consent) is in [Set up agent access](/sign-in-setup/agent-access), and the device code grant in [Device code sign-in](/authentication/device-code).

All of them are under `/api/v1/auth/oauth2` on your BuildBase server, [https://api.console.buildbase.app](https://api.console.buildbase.app) on BuildBase's cloud, and each one names your organization with `?org=<orgId>`.

```bash
curl -s -X POST "https://api.console.buildbase.app/api/v1/auth/oauth2/introspect?org=$BUILDBASE_ORG_ID" \
  -d "token=$REFRESH_TOKEN" \
  -d "client_id=$CLIENT_ID" \
  -d "client_secret=$CLIENT_SECRET"
```

| Method   | Path                                      | Standard | Authenticated by                         |
| -------- | ----------------------------------------- | -------- | ---------------------------------------- |
| `POST`   | `/api/v1/auth/oauth2/register`            | RFC 7591 | Nothing: open while registration is on   |
| `GET`    | `/api/v1/auth/oauth2/register/{clientId}` | RFC 7592 | The registration access token, as Bearer |
| `PUT`    | `/api/v1/auth/oauth2/register/{clientId}` | RFC 7592 | The registration access token, as Bearer |
| `DELETE` | `/api/v1/auth/oauth2/register/{clientId}` | RFC 7592 | The registration access token, as Bearer |
| `POST`   | `/api/v1/auth/oauth2/introspect`          | RFC 7662 | The client's credentials                 |
| `POST`   | `/api/v1/auth/oauth2/revoke`              | RFC 7009 | The client's credentials                 |

Your authorization server metadata, `/.well-known/oauth-authorization-server/org/<orgId>`, lists them as `registration_endpoint` (only while registration is on), `introspection_endpoint` and `revocation_endpoint`, each with its `?org=`.

Errors on these endpoints come in OAuth's shape, `{ "error", "error_description" }`. A missing or unknown `?org=` is `400 invalid_request` on every one of them.

## Register a client

`POST /api/v1/auth/oauth2/register?org=<orgId>`, JSON. An agent registers itself with no admin involved. It works only while **Let agents register themselves** is on and a base client is picked in your agent access settings (see [Set up agent access](/sign-in-setup/agent-access)); every client registered this way copies that base client's token, profile and revoke URLs, and is an agent client: PKCE is required and each person approves it on the consent screen.

```bash
curl -s -X POST "https://api.console.buildbase.app/api/v1/auth/oauth2/register?org=$BUILDBASE_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "Notes Helper",
    "redirect_uris": ["https://notes-helper.example/oauth/callback"],
    "token_endpoint_auth_method": "none"
  }'
```

| Field                                                                                            | Type                  | Required | Description                                                                                                                                                                        |
| ------------------------------------------------------------------------------------------------ | --------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `redirect_uris`                                                                                  | `string[]`            | Yes      | 1 to 20 URIs of at most 2000 characters. Each must be `https`, or `http` on a loopback host, with no fragment, no user name or password, and no wildcard                           |
| `client_name`                                                                                    | `string`              | No       | At most 200 characters. Cleaned of control and invisible characters. Missing, or a name reserved in your organization (yours, or one of your own clients'), it is `Dynamic Client` |
| `token_endpoint_auth_method`                                                                     | `string`              | No       | `client_secret_post` (the default), `client_secret_basic`, or `none` for a public client that holds no secret and proves itself with PKCE alone                                    |
| `grant_types`                                                                                    | `string[]`            | No       | Ask for `urn:ietf:params:oauth:grant-type:device_code` to get the device code grant. Given only when the base client has it on                                                     |
| `scope`                                                                                          | `string`              | No       | Accepted; scopes are asked for at sign-in, so the answer's `scope` is empty                                                                                                        |
| `contacts`, `logo_uri`, `client_uri`, `policy_uri`, `tos_uri`, `software_id`, `software_version` | `string` / `string[]` | No       | Kept with the client as a record of who registered it. Never shown on the consent screen                                                                                           |

Other fields are accepted and ignored.

**`201 Created`:**

```json
{
  "client_id": "k3J9...",
  "client_id_issued_at": 1762560000,
  "registration_access_token": "Zq81...",
  "registration_client_uri": "https://api.console.buildbase.app/api/v1/auth/oauth2/register/k3J9...?org=<orgId>",
  "token_endpoint_auth_method": "none",
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "redirect_uris": ["https://notes-helper.example/oauth/callback"],
  "client_name": "Notes Helper",
  "scope": ""
}
```

A confidential client (`client_secret_post` or `client_secret_basic`) also gets `client_secret` and `client_secret_expires_at: 0` (it does not expire). A public client never gets a secret. Store `registration_access_token`: it is shown once, and it is what manages the registration below.

| Status | `error`                   | When                                                                                                                  |
| ------ | ------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `400`  | (the request validator's) | No `redirect_uris`, or a field of the wrong type or past its length                                                   |
| `400`  | `invalid_redirect_uri`    | A redirect URI that is not `https` or loopback `http`, or that has a wildcard, a fragment or a user name              |
| `400`  | `invalid_client_metadata` | An unsupported `token_endpoint_auth_method`, or registration is on but its base client is missing or has no token URL |
| `403`  | `access_denied`           | Registration is off for the organization, or it has reached its limit of self-registered clients                      |
| `429`  |                           | More than 5 registrations a minute from one address, or 10 clients an hour from one network for one organization      |
| `503`  | `temporarily_unavailable` | Another registration for the same organization is being made. Sent with `Retry-After: 1`                              |
| `500`  | `invalid_client_metadata` | The registration failed                                                                                               |

At the limit, unused self-registered clients are removed first, oldest first, and the registration goes ahead if that freed room. What counts as unused is in [Set up agent access](/sign-in-setup/agent-access).

## Manage a registration

The three `/register/{clientId}` routes take the registration access token in `Authorization: Bearer <token>`, never the client secret. They work for a self-registered client only, and keep working after you turn registration off, so a client can always read or delete itself.

**The token changes on every read and update.** Each successful `GET` and `PUT` answers a new `registration_access_token`, and the one sent stops working. Keep the new one each time.

Any problem with the token, including a client that does not exist or was created in the console, is the same answer, so a caller cannot tell which:

```json
{
  "error": "invalid_token",
  "error_description": "Invalid registration access token."
}
```

with `401` and `WWW-Authenticate: Bearer error="invalid_token"`. These routes allow 30 requests a minute per address (`429` past that); any other method on the path is `405` with `Allow: GET, PUT, DELETE`.

### Read it

`GET /api/v1/auth/oauth2/register/{clientId}?org=<orgId>` answers `200` with the client as it stands: `client_id`, `client_secret` and `client_secret_expires_at` (confidential clients only), the new `registration_access_token`, `registration_client_uri`, `redirect_uris`, `client_name`, `token_endpoint_auth_method`, `grant_types`, `response_types` and `scope`.

`redirect_uris` lists literal URIs only. A wildcard pattern the client inherited from its base client still works at sign-in, but is left out of the list.

### Update it

`PUT /api/v1/auth/oauth2/register/{clientId}?org=<orgId>`, JSON. Send the client's metadata whole: only `redirect_uris` and `client_name` change, and the rest comes from the base client.

```bash
curl -s -X PUT "https://api.console.buildbase.app/api/v1/auth/oauth2/register/$CLIENT_ID?org=$BUILDBASE_ORG_ID" \
  -H "Authorization: Bearer $REGISTRATION_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "'"$CLIENT_ID"'",
    "client_name": "Notes Helper",
    "redirect_uris": ["https://notes-helper.example/oauth/callback", "http://127.0.0.1:8765/callback"]
  }'
```

| Field           | Required | Description                                                                                      |
| --------------- | -------- | ------------------------------------------------------------------------------------------------ |
| `client_id`     | Yes      | Must be the client's own ID                                                                      |
| `redirect_uris` | Yes      | Replaces the list: 1 to 20 URIs of at most 2000 characters, under the same rules as registration |
| `client_name`   | No       | Replaces the name. Left out, the name goes back to `Dynamic Client`, as RFC 7592 asks            |
| `client_secret` | No       | If sent, it must be the client's current secret. It cannot be changed                            |

Fields the server assigned (`registration_access_token`, `registration_client_uri`, `client_id_issued_at`, `client_secret_expires_at`) may be echoed back and are ignored. The answer is `200` with the same body as a read, and a new token. Each update is in your auth log with the redirect URIs and the name before and after.

| Status | `error`                   | When                                                                                                                                                       |
| ------ | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_client_metadata` | `client_id` missing or not the client's, a different `client_secret`, or `redirect_uris` missing, empty, longer than 20 or with a URI past 2000 characters |
| `400`  | `invalid_redirect_uri`    | A redirect URI that is not `https` or loopback `http`                                                                                                      |

### Delete it

`DELETE /api/v1/auth/oauth2/register/{clientId}?org=<orgId>` answers `204` with no body. It ends everything given to the client: people's consents, the sessions its grants opened and its refresh tokens, then removes the client. Your **Application revoke URL** hears `client_deleted` for each person who had approved it, and the auth log records `client_deleted`.

## Introspect a token

`POST /api/v1/auth/oauth2/introspect?org=<orgId>`, form-encoded or JSON. A resource server asks whether a token is live.

BuildBase issues the refresh tokens, so those are what it can introspect. The access tokens your clients use are minted by your own server (your **Application token URL**), and your server is their authority.

| Parameter                    | Required | Description                                                                         |
| ---------------------------- | -------- | ----------------------------------------------------------------------------------- |
| `token`                      | Yes      | The refresh token                                                                   |
| `token_type_hint`            | No       | Accepted. It does not narrow the search: refresh tokens are the only kind looked up |
| `client_id`, `client_secret` | Yes      | In the body, or as HTTP Basic. A public client (`none`) sends its `client_id` alone |

The metadata advertises `client_secret_basic` and `client_secret_post` for introspection.

A live token answers `200`:

```json
{
  "active": true,
  "client_id": "k3J9...",
  "sub": "6650f1c2a8b4e3d2c1b0a998",
  "iss": "https://api.console.buildbase.app/org/<orgId>",
  "scope": "openid profile notes:read",
  "aud": ["https://notes.acme.example"],
  "exp": 1765152000,
  "iat": 1762560000
}
```

`scope` and `aud` appear when the grant has them, and `exp` when the token has an end: the earliest of its own expiry and your organization's refresh token lifetimes. `token_type` is left out on purpose, since the standard defines it for access tokens. `iss` is your organization's issuer, `<server>/org/<orgId>`, as in the metadata.

Anything else answers `200` with `{ "active": false }` and nothing more: an unknown token, another client's token, an expired, rotated or revoked one, one past your lifetimes, a token signed with a secret since replaced, and a token whose person was deleted or blocked. The answer never says which.

| Status | `error`           | When                                                                                              |
| ------ | ----------------- | ------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_request` | No `token`, or a parameter that is not a single value of at most 4096 characters                  |
| `401`  | `invalid_client`  | No `client_id`, an unknown client or a wrong secret. With `WWW-Authenticate` when Basic was tried |
| `429`  |                   | More than 30 requests a minute from one address                                                   |

## Revoke a token

`POST /api/v1/auth/oauth2/revoke?org=<orgId>`, form-encoded or JSON, with the same `token`, `token_type_hint` and client credentials as introspection. Public clients (`none`) send their `client_id` alone.

```bash
curl -s -X POST "https://api.console.buildbase.app/api/v1/auth/oauth2/revoke?org=$BUILDBASE_ORG_ID" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d "token=$REFRESH_TOKEN"
```

When the refresh token belongs to the calling client, it stops working; for an agent client, every token in its rotation chain goes with it. The sessions the grant opened end at once, and your **Application revoke URL** hears `token_revoked` for the person.

An authenticated client always gets `200` with an empty body, whether the token was found, belonged to another client, or was not sent at all, so revocation cannot be used to find tokens. The errors are introspection's: `401 invalid_client` for bad credentials, `400 invalid_request` for a parameter that is not a single value, and `429` past 30 requests a minute.

## Next steps

- [Set up agent access](/sign-in-setup/agent-access) - turn on self-registration, pick the base client and the revoke URL
- [Sessions and tokens](/authentication/sessions-and-tokens) - how refresh tokens are stored and how long they last
- [Device code sign-in](/authentication/device-code) - the device authorization and token endpoints
