Skip to content

/token

POST/tokenissuer host

Exchanges an authorization code, a refresh token, or a machine client’s credentials for tokens. The body is form-encoded (application/x-www-form-urlencoded); a JSON body is refused with invalid_request. Every answer carries Cache-Control: no-store and Pragma: no-cache.

Grant For
authorization_code Every client a user logs in through: spa, native, web.
refresh_token Renewing those tokens without the user.
client_credentials Machine clients, for themselves.

Any other grant_type (token exchange, the device flow, the implicit or password grants) is unsupported_grant_type.

Client How it authenticates
spa, native (public) client_id in the body, no secret, and a DPoP proof with every request.
web, machine (confidential) HTTP Basic: Authorization: Basic base64(client_id:client_secret), each half form-encoded first (client_secret_basic).

A confidential client that sends no Basic header is refused with invalid_client, even with client_secret in the body: client_secret_post is not supported, and neither is private_key_jwt. A public client that sends a secret is refused too. A client_id in the body that differs from the Basic header is invalid_request. Every invalid_client answer is 401 with WWW-Authenticate: Basic.

Send a DPoP header with a proof for POST {issuer}/token (no ath: no access token is presented here).

  • Public clients must send one with every grant; without it the answer is invalid_dpop_proof (“public clients must send a DPoP proof”).
  • Confidential clients may. A web client’s backend usually does not.

The tokens of an authorization code exchange are bound to the proof’s key whenever a proof was sent: the access token carries cnf.jkt, token_type is DPoP, and the refresh token can only be used with a proof from the same key. A bound refresh token stays bound across rotations. Machine-client tokens are never bound. See DPoP.

Parameter Required Meaning
grant_type yes authorization_code
code yes The code from /authorize or the embedded login.
code_verifier yes The PKCE verifier: 43 to 128 unreserved characters whose S256 is the request’s code_challenge.
redirect_uri for codes from /authorize The same redirect_uri the code was issued for.
client_id public clients The client.

Every refusal of the code itself (another client’s, expired, already used, a wrong verifier or redirect URI, a session or user that is no longer active) is invalid_grant “the code is invalid or expired”. The audience of the tokens is the one the code was issued for; resource is not read here.

A code is good for 60 seconds and one exchange. A code presented a second time is treated as stolen: the tokens issued from it are revoked, and so is the session when it came from an embedded login.

POST /token HTTP/1.1
Host: your-app.auth.dev.seek.services
Content-Type: application/x-www-form-urlencoded
DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7…
grant_type=authorization_code&code=Xv3n…&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk&client_id=your-app-spa
{
"access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6ImF0K2p3dCIsImtpZCI6…",
"token_type": "DPoP",
"expires_in": 300,
"refresh_token": "kq8V…",
"refresh_expires_in": 2592000,
"id_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6…",
"scope": "openid profile email offline_access"
}

A web client’s backend authenticates with Basic instead, sends redirect_uri, and gets "token_type": "Bearer" (no proof, so no binding).

Parameter Required Meaning
grant_type yes refresh_token
refresh_token yes The current refresh token.
client_id public clients The client.
scope no A narrower scope than was granted. A wider one is invalid_scope.
resource no An API to get this access token for instead of the granted one.
POST /token HTTP/1.1
Host: your-app.auth.dev.seek.services
Content-Type: application/x-www-form-urlencoded
DPoP: eyJ0eXAiOiJkcG9wK2p3dCIs…
grant_type=refresh_token&refresh_token=kq8V…&client_id=your-app-spa

Every refresh returns a new refresh token, and the one presented is used up. There is no grace window: of two requests that present the same token, one gets new tokens and the other counts as a reuse. Clients that refresh from several tabs or threads must take turns (auth-js and the Rust web client do).

A refresh also counts as use of the session, which moves its inactivity timeout on. Each new refresh token expires at the sooner of its own lifetime and the session’s end. Narrowing the scope so that it no longer has offline_access returns no new refresh token, and without openid no ID token.

A refresh token that was already used, presented again, ends everything that came from that login: every refresh token of its family, every token of its session, and the session itself, which records refresh.reuse_detected and session.revoked in the audit log. The user gets one email about it. The answer is invalid_grant. A used token keeps its expiry, so a copy replayed days later is still recognised. See Tokens and sessions.

Other refusals do not use the token up: an expired or revoked token, or a proof from the wrong key (invalid_dpop_proof), leave the family alone.

invalid_grant is also the answer when the session or user is no longer active, or when the app now needs an email address the user does not have.

A refresh grant is committed within 8 seconds of reaching the service, or not at all. The discovery document says so in refresh_grant_committed_within_ms. A refresh the service came to too late is refused with 503 temporarily_unavailable and has used nothing up, so present the same token again. That covers one that waited for a database connection or a lock, or that was more than 4 seconds old when it would have used the token.

A client that sent a refresh and heard nothing back cannot tell whether the token was used up. Presenting it again before that bound has passed could count as a reuse. The Rust web client waits for the bound to pass, then asks introspection before it presents the token again.

Parameter Required Meaning
grant_type yes client_credentials
resource unless the client has a default API The API the token is for: one of the client’s app, or one it was granted.

Only machine clients may use this grant (others get unauthorized_client), with Basic authentication. The answer has an access token and nothing else: no refresh token, no ID token, scope is "", and token_type is Bearer. The token’s sub is the client’s client_id; its roles and permissions are the roles given to the client. The account API cannot be named: invalid_target “name the API the token is for with resource”.

Terminal window
curl -s https://your-app.auth.dev.seek.services/token \
-u 'your-app-orders-job:<client secret>' \
-d grant_type=client_credentials \
--data-urlencode 'resource=orders-api'
{
"access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6ImF0K2p3dCIs…",
"token_type": "Bearer",
"expires_in": 300,
"scope": ""
}

expires_in is the environment’s machine token lifetime. The discovery document lists the grant in grant_types_supported.

Field Present Meaning
access_token always An ES256 JWT for one audience. See Tokens and claims.
token_type always DPoP when the token is bound to a key, else Bearer.
expires_in always Seconds: the environment’s access token lifetime, or machine token lifetime.
refresh_token with offline_access Opaque, 43 characters.
refresh_expires_in with a refresh token Seconds until the refresh token expires if it is not used. Not in the OAuth standard: use it to end your own session record when the service’s will have ended.
id_token with openid The ID token.
scope always The granted scope, space-separated; "" for a machine token.

An access token has exactly one audience (aud), the API it is for:

  • With resource, it must be the account API (account), an API of the client’s own app, or an API of another app of the group that the client was granted. Anything else, an unknown audience included, is invalid_target “this client may not ask for that resource”.
  • Without resource, it is the client’s default API, or account when it has none.

A token for another app’s API is issued only if that app lets the user in, and has the email address it needs; otherwise access_denied. On a refresh, a resource the client may no longer name is invalid_target, and a granted audience that is no longer allowed is invalid_grant. See Calling your API.

Errors have the OAuth shape, { "error", "error_description" }; see OAuth errors.

error Status When
invalid_request 400 A body that is not form-encoded, a missing grant_type, code, code_verifier or refresh_token, or mismatched client ids.
invalid_client 401 Missing, unknown or wrong client credentials; a secret from a public client; a confidential client without Basic.
invalid_dpop_proof 400 A public client without a proof, a proof that does not verify or was replayed, or one from the wrong key for a bound refresh token.
invalid_grant 400 The code or refresh token is not good, was reused, or its session or user has ended.
invalid_scope 400 A refresh asked for more scope than was granted.
invalid_target 400 resource names an API the client may not ask for.
unauthorized_client 400 client_credentials from a client that is not a machine client.
unsupported_grant_type 400 Any other grant.
access_denied 403 The app that owns the requested API does not let this user in.
temporarily_unavailable 503 A refresh the service came to too late, or could not finish in time. Nothing was used up: present the same token again.
server_error 500 Something failed on the server.