StudioHomepage
ServicesAuthenticationHTTP APIAuthorization server

Get a token

POST
/oauth/token

The token endpoint (RFC 6749 §3.2). Select the grant with grant_type. authorization_code redeems a code with its PKCE verifier (RFC 6749 §4.1.3, RFC 7636 §4.5). refresh_token renews a user session for the same client that received it (RFC 6749 §6). Disabled clients cannot redeem grants. urn:ietf:params:oauth:grant-type:device_code completes a device authorization (RFC 8628 §3.4). client_credentials gets a token for a client, such as a Workload, that authenticates with a private_key_jwt assertion (RFC 6749 §4.4, RFC 7523 §2.2). urn:ietf:params:oauth:grant-type:jwt-bearer gets a token for a client with a token from an identity provider that the client trusts (RFC 7523 §2.1). urn:ietf:params:oauth:grant-type:token-exchange narrows a Spiral access token to some of its audiences and scopes (RFC 8693). Every grant may name several resources (RFC 8707), each of which the client's grant and registration allow; a token names them, or every resource of the grant when the request names none. Public clients send only client_id. Client secrets are not accepted. Tokens that a client gets for itself expire after at most 15 minutes, and never after the JWT that they come from. The response names the API URL to call in resource.

Request Body

application/x-www-form-urlencoded
  1. body

Redeem an authorization code (RFC 6749 §4.1.3) with its PKCE verifier (RFC 7636 §4.5). A code works once, and only for the client that it was issued to.

grant_type*unknown
client_id*string
code*string
code_verifier*string
redirect_uri?string

The redirect URI of the authorization request.

Formaturi
resource?string

Repeatable. Narrows the token to these resources of the grant (RFC 8707 §2.2).

Formaturi
client_assertion_type?string

For a third-party application whose registration names a jwks_uri.

client_assertion?string

A private_key_jwt assertion (RFC 7523 §2.2).

Response Body

The token (RFC 6749 §5.1).

application/json
  1. response

A successful token response (RFC 6749 §5.1).

access_token*string

A JWT access token (RFC 9068).

token_type*string
expires_in*integer

The lifetime of the access token in seconds.

Formatuint64
refresh_token*|

A refresh token for a user grant, or null.

scope?string

The granted scopes (RFC 6749 §5.1). Omitted for first-party applications.

id_token?string

The ID token of a first-party user grant (OpenID Connect Core §3.1.3.3). Omitted otherwise.

resource?string

The API URL that the access token is for. Call this URL with the token.

Formaturi
issued_token_type?string

The type of the issued token (RFC 8693 §2.2.1). Only for token exchange.

authorization_details?array<>

The authorization details that an exchanged token carries (RFC 9396 §7).

curl -X POST 'https://auth.spiraldb.com/oauth/token' \  -H 'Content-Type: application/x-www-form-urlencoded' \  -d 'grant_type=authorization_code&client_id=string&code=string&code_verifier=string'
{  "access_token": "string",  "token_type": "Bearer",  "expires_in": 0,  "refresh_token": "string",  "scope": "string",  "id_token": "string",  "resource": "http://example.com",  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",  "authorization_details": [    {}  ]}