Skip to content

Revocation and introspection

POST/revokeissuer host

Ends a refresh token (RFC 7009). This is how a client that logged in through the embedded login signs out.

Parameter Required Meaning
token yes The refresh token.
client_id public clients The client.

The body is form-encoded. The client authenticates as at /token: a public client with client_id, a confidential one with Basic. token_type_hint is not read.

What it does:

  • A refresh token of this client is revoked, with every refresh token of its family.
  • If its session came from the embedded login (it has no session cookie on the issuer host), the session ends too, with all its tokens, and session.revoked is recorded with the reason logout.
  • A session made on the hosted page is left alone: it belongs to the browser’s cookie, and ends at /logout.
  • Anything else (an access token, an unknown value, another client’s token) changes nothing.

The answer is 200 {} in every case, so a caller learns nothing about tokens that are not its own.

POST /revoke HTTP/1.1
Host: your-app.auth.dev.seek.services
Content-Type: application/x-www-form-urlencoded
token=kq8V…&client_id=your-app-spa
{}

After it, a refresh with that token answers invalid_grant, and /userinfo refuses the session’s access tokens with 401. Access tokens themselves cannot be taken back: an API that verifies them offline accepts them until they expire, which is why they are short-lived. See Sessions.

POST/introspectissuer host

Says whether a token is active, and what it carries (RFC 7662). For confidential clients only (web and machine), with Basic authentication; a public client gets 401 invalid_client “introspection is for confidential clients”.

Parameter Required Meaning
token yes An access token or a refresh token.

It is active when it verifies, has not expired, its session is still active, and the caller may see it: the token was issued to the calling client, or its audience is the caller’s default API (or account, for a caller without one). The answer is every claim of the token, plus active and token_type:

POST /introspect HTTP/1.1
Host: your-app.auth.dev.seek.services
Authorization: Basic eW91ci1hcHAtd2ViOnNlY3JldA==
Content-Type: application/x-www-form-urlencoded
token=eyJhbGciOiJFUzI1NiIsInR5cCI6ImF0K2p3dCIs…
{
"active": true,
"token_type": "Bearer",
"iss": "https://your-app.auth.dev.seek.services",
"sub": "0b9f6c1e-4d7a-4c55-9a1e-2f3b8d6c7e10",
"aud": "orders-api",
"client_id": "your-app-web",
"scope": "openid email offline_access",
"sid": "5d2c…",
"acr": "aal1",
"amr": ["email"],
"roles": ["editor"],
"permissions": ["orders:read"],
"iat": 1791460990,
"exp": 1791461290,
"auth_time": 1791460980,
"jti": "…"
}

token_type is DPoP for a bound token. So an API’s backend, as a confidential client whose default API is that API, can introspect the tokens users bring it.

Only the caller’s own, unused, unrevoked and unexpired, with an active session:

{
"active": true,
"token_type": "refresh_token",
"client_id": "your-app-web",
"scope": "openid email offline_access",
"sub": "0b9f6c1e-4d7a-4c55-9a1e-2f3b8d6c7e10",
"aud": "orders-api",
"iss": "https://your-app.auth.dev.seek.services",
"exp": 1794052990,
"sid": "5d2c…"
}

Any other token, one the caller may not see, and a machine client’s access token (it has no session) answer:

{ "active": false }

To check a machine client’s token, verify it as a JWT against the key set.