Skip to content
BuildBase

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"
MethodPathStandardAuthenticated by
POST/api/v1/auth/oauth2/registerRFC 7591Nothing: open while registration is on
GET/api/v1/auth/oauth2/register/{clientId}RFC 7592The registration access token, as Bearer
PUT/api/v1/auth/oauth2/register/{clientId}RFC 7592The registration access token, as Bearer
DELETE/api/v1/auth/oauth2/register/{clientId}RFC 7592The registration access token, as Bearer
POST/api/v1/auth/oauth2/introspectRFC 7662The client's credentials
POST/api/v1/auth/oauth2/revokeRFC 7009The 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"
  }'
FieldTypeRequiredDescription
redirect_urisstring[]Yes1 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_namestringNoAt 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_methodstringNoclient_secret_post (the default), client_secret_basic, or none for a public client that holds no secret and proves itself with PKCE alone
grant_typesstring[]NoAsk for urn:ietf:params:oauth:grant-type:device_code to get the device code grant. Given only when the base client has it on
scopestringNoAccepted; 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_versionstring / string[]NoKept 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.

StatuserrorWhen
400(the request validator's)No redirect_uris, or a field of the wrong type or past its length
400invalid_redirect_uriA redirect URI that is not https or loopback http, or that has a wildcard, a fragment or a user name
400invalid_client_metadataAn unsupported token_endpoint_auth_method, or registration is on but its base client is missing or has no token URL
403access_deniedRegistration is off for the organization, or it has reached its limit of self-registered clients
429More than 5 registrations a minute from one address, or 10 clients an hour from one network for one organization
503temporarily_unavailableAnother registration for the same organization is being made. Sent with Retry-After: 1
500invalid_client_metadataThe 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"]
  }'
FieldRequiredDescription
client_idYesMust be the client's own ID
redirect_urisYesReplaces the list: 1 to 20 URIs of at most 2000 characters, under the same rules as registration
client_nameNoReplaces the name. Left out, the name goes back to Dynamic Client, as RFC 7592 asks
client_secretNoIf 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.

StatuserrorWhen
400invalid_client_metadataclient_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
400invalid_redirect_uriA 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.

ParameterRequiredDescription
tokenYesThe refresh token
token_type_hintNoAccepted. It does not narrow the search: refresh tokens are the only kind looked up
client_id, client_secretYesIn 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.

StatuserrorWhen
400invalid_requestNo token, or a parameter that is not a single value of at most 4096 characters
401invalid_clientNo client_id, an unknown client or a wrong secret. With WWW-Authenticate when Basic was tried
429More 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