Skip to main content
For AI agents: a documentation index is available at https://docs.coverbase.com/llms.txt. This page is also available in markdown by appending .md to the URL.
Your Coverbase representative turns on the third-party lifecycle features, including OAuth clients, for your organization.
An integration that cannot store a long-lived ak_* key can use the OAuth 2.0 client credentials grant instead. An admin creates an OAuth client: a public client_id and a client_secret shown once. The integration trades them for a bearer token that lasts at most an hour, and sends that token wherever an ak_* key goes. A token acts exactly like an ak_* key: it authenticates as your organization’s API service account, every public route and the IP allowlist apply unchanged, and its calls are recorded in the public API audit log. It carries the elevated scopes the client was granted, or fewer if the token request narrows them. For a walkthrough, see OAuth 2.0 client credentials.

​
Get a token

​
POST
POST /v1/oauth/token
Follows RFC 6749 section 4.4. The body is form-encoded (application/x-www-form-urlencoded), not JSON. Send the client ID and secret as HTTP Basic credentials (preferred), or as client_id and client_secret form fields, but not both.

​
Request body

​
string
required
Must be client_credentials.
​
string
Space-separated scopes to request. Optional. It can only narrow what the client was granted: asking for a scope the client does not hold fails with invalid_scope. Omit it to get every scope the client holds.
​
string
The client ID (cbci_...), when not sent in HTTP Basic.
​
string
The client secret (cbcs_...), when not sent in HTTP Basic.

​
Example request

cURL

​
Example response

The response carries Cache-Control: no-store. Send the token as Authorization: Bearer cbat_... until expires_in seconds pass, then request a new one. A client holds at most 50 live tokens. Requesting a 51st revokes its oldest, so an integration should reuse a token until it expires rather than request one per call.
​
string
The bearer token, prefixed cbat_.
​
string
Always Bearer.
​
integer
Lifetime in seconds: the client’s token lifetime, between 300 and 3600.
​
string
The scopes the token carries, space-separated. Empty for a client with no elevated scopes.

​
Errors

Errors follow RFC 6749 section 5.2, not the coded envelope:

​
List clients

​
GET
GET /v1/api-oauth-clients
Returns { "clients": [ ... ] }, one client object per client, revoked ones included. Secrets are never returned.

​
Create a client

​
POST
POST /v1/api-oauth-clients
Returns 201 Created with the client object plus client_secret. This is the only time the secret is returned. Coverbase stores only its SHA-256 digest and last four characters.
​
string
required
A label, 1 to 200 characters, such as “Archer sync”.
​
string[]
Elevated scopes to grant: keys:manage, audit:read, banking:read, review:sensitive_changes. Granting any needs an admin dashboard JWT; any other caller gets 403 scope_grant_forbidden. Omit for a client with standard access.
​
integer
How long each token lives, 300 to 3600. Default 3600.
cURL

​
Revoke a client

​
POST
POST /v1/api-oauth-clients/{client_row_id}/revoke
Revokes the client and deletes every token it issued. Returns the client object with revoked_at set. A server that already cached a token can keep accepting it for a few seconds. Creating and revoking clients are recorded in the activity log.

​
The client object

​
string
The client’s row ID, used in the revoke path.
​
string
The label.
​
string
The public client ID, prefixed cbci_.
​
string
The last four characters of the secret, to tell clients apart.
​
string[]
The elevated scopes granted.
​
integer
Token lifetime in seconds.
​
integer
Unix seconds.
​
integer | null
When the client last obtained a token.
​
integer | null
When it was revoked, or null.