/token
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 authentication
Section titled “Client authentication”| 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.
Authorization code
Section titled “Authorization code”| 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.1Host: your-app.auth.dev.seek.servicesContent-Type: application/x-www-form-urlencodedDPoP: 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).
Refresh token
Section titled “Refresh token”| 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.1Host: your-app.auth.dev.seek.servicesContent-Type: application/x-www-form-urlencodedDPoP: eyJ0eXAiOiJkcG9wK2p3dCIs…
grant_type=refresh_token&refresh_token=kq8V…&client_id=your-app-spaRotation
Section titled “Rotation”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.
Reuse detection
Section titled “Reuse detection”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 that gets no answer
Section titled “A refresh that gets no answer”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.
Client credentials
Section titled “Client credentials”| 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”.
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.
The response
Section titled “The response”| 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. |
Resource and audience
Section titled “Resource and audience”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, isinvalid_target“this client may not ask for that resource”. - Without
resource, it is the client’s default API, oraccountwhen 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
Section titled “Errors”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. |