Skip to content

The v1 docs follow nauthera-server's main branch and its 0.x releases on the way to 1.0, so fields and APIs can still change.

v1

invalid_token

Docs version v1 (main)Nauthera is pre-1.0, in a design-partner program

The access token presented is missing, invalid, expired, revoked or not usable here (RFC 6750 §3.1).

Meaning

Sent with 401 and a WWW-Authenticate challenge by /userinfo (in a problem document whose code is invalid_token) and by /register and /register/{client_id} for the initial and registration access tokens. The token does not verify, has expired, names another audience or organization, belongs to a revoked grant, is DPoP-bound and sent as Bearer or with another key's proof, or, at /register, carries no org claim. An unknown client_id on /register/{client_id} answers it too, so client ids cannot be probed. /introspect never sends it: it answers active: false.

Impact

The application cannot read the user's claims or manage its registration with that token. Normal when an access token has expired; otherwise a sign that the grant was revoked or the token is used where it does not belong.

Diagnosis

  1. Refusals at /userinfo are recorded as oauth.token.presented with a finer reason (token_expired, missing_expiry, audience_mismatch, invalid_dpop_proof, unauthenticated) and a cause such as token_kid_unknown, token_issuer_mismatch, token_signature_invalid or grant_revoked. Registration refusals are recorded as client.registration.attempted. Find them by X-Request-ID.
  2. Check the token's exp, aud and iss, and whether it is DPoP-bound (cnf.jkt).

Mitigation

  • As a client developer: refresh or sign in again for a new token; send a bound token with the DPoP scheme and a proof. For /register, use a token with the nauthera.clients:register scope and an org claim, and keep the registration_access_token from the registration response.
  • As an operator: if every token of an organization fails with token_kid_unknown, check the organization's signing keys and the key-encryption key.
  • As a user: sign in to the application again.

Escalation

If freshly issued tokens are refused, open an issue with the request id, the server version and the recorded reason and cause. Never attach the token itself.

OAuth error runbooks · Generated from internal/runbook/oauth.yaml in nauthera-server.