Revocation and introspection
Revocation
Section titled “Revocation”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.revokedis recorded with the reasonlogout. - 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.1Host: your-app.auth.dev.seek.servicesContent-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.
Introspection
Section titled “Introspection”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. |
An access token
Section titled “An access 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.1Host: your-app.auth.dev.seek.servicesAuthorization: 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.
A refresh token
Section titled “A refresh token”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…"}Everything else
Section titled “Everything else”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.