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, and the device code grant in Device code sign-in.
All of them are under /api/v1/auth/oauth2 on your BuildBase server, https://api.console.buildbase.app on BuildBase's cloud, and each one names your organization with ?org=<orgId>.
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); 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.
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:
{
"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.
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:
{
"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.
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:
{
"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.
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 - turn on self-registration, pick the base client and the revoke URL
- Sessions and tokens - how refresh tokens are stored and how long they last
- Device code sign-in - the device authorization and token endpoints