Skip to main content
POST
Exchange an access key for a bearer token

Body

An OAuth 2.0 token request. Form-encoded is what RFC 6749 specifies and what client libraries send; JSON is accepted too.

Client credentials may be sent as HTTP Basic (Authorization: Basic base64(key_id:secret), which is what most libraries do by default) or as client_id and client_secret fields. Basic wins if both are present.

grant_type
enum<string>
required

client_credentials is the one to use for a service account: it exchanges an access key pair for a token, and needs nothing else.

authorization_code and refresh_token belong to the interactive login a person runs (basaltic login), where the token names a USER rather than a service account. They are driven by the CLI, not written by hand. Check the authorization-server metadata document before branching on them — they are advertised only where an authorization endpoint is configured.

Available options:
client_credentials,
authorization_code,
refresh_token
Example:

"client_credentials"

client_id
string

The access key id. Omit when using HTTP Basic.

Example:

"BYCLD1a2b3c4d5e6f7"

client_secret
string<password>

The secret access key. Omit when using HTTP Basic.

duration_seconds
integer

Requested token lifetime. A Basaltic extension, not an OAuth parameter — omit it and you get the default. Values outside the range are clamped into it rather than refused, so asking for a day yields the longest token allowed.

Required range: 900 <= x <= 43200
Example:

3600

code
string

The authorization code from the consent redirect. Single use, and valid for five minutes. authorization_code grant only.

code_verifier
string

The PKCE verifier whose SHA-256 was sent as code_challenge when the flow started (RFC 7636). Required with authorization_code: it is what proves this is the client that began the flow, since a CLI holds no client secret.

redirect_uri
string

The same redirect_uri the code was issued for. Re-checked here, so a code cannot be redeemed against a different destination.

Example:

"http://127.0.0.1:53682/callback"

refresh_token
string

refresh_token grant only. Renews a user session without another trip through the browser. Rotated on every use — store the new one.

Response

A bearer token

RFC 6749 token response.

access_token
string
required

Send as Authorization: Bearer <token>. Opaque to clients: do not parse it, and do not key anything on the token string.

Example:

"eyJhbGciOiJFUzI1NiIsInR5cCI6ImF0K2p3dCIsImtpZCI6Ii4uLiJ9..."

token_type
enum<string>
required
Available options:
Bearer
Example:

"Bearer"

expires_in
integer
required

Seconds until the token expires.

Example:

3600

refresh_token
string

Returned only by the user grants (authorization_code and refresh_token). Present it to the refresh_token grant to renew without another browser round trip; it is ROTATED on each use, so replace the stored copy every time.

A service account gets none. It already holds a long-lived access key and can simply run client_credentials again, so a refresh token would be a second credential to store for no gain.