Revoke
This page helps you end a grant from your app, typically when a user signs out, with the revocation endpoint, /auth/revoke.
It’s the RFC 7009 token revocation endpoint, the revocation_endpoint in the discovery document. A grant is what one sign-in gave your app: its refresh token, every refresh token that one was rotated into, and every access token issued with them.
Revoke a token
Section titled “Revoke a token”-
Send the refresh token, or an access token, with your client’s credentials:
POST /auth/revoke HTTP/1.1Host: auth.example.comContent-Type: application/x-www-form-urlencodedAuthorization: Basic bXktYXBwOm15LXNlY3JldA==token=eyJhbGciOiJSUzI1NiIsImtpZCI6Ii4uLiJ9... -
The auth server ends the grant and answers with an empty body:
HTTP/1.1 200 OK -
Delete the tokens your app holds.
Sending the refresh token ends the whole grant, and so does an access token of the grant that hasn’t expired, so one call is enough. An expired access token ends nothing, though it’s answered 200 too, so send the refresh token when your app has one. A library that revokes the access token and then the refresh token gets 200 for both.
What revoking ends
Section titled “What revoking ends”Revoking ends the grant the token belongs to, at once:
- The refresh token is refused at the token endpoint, and so is every refresh token of the grant.
- Every access token of the grant is refused at
/userinfoand the auth server’s APIs.
It leaves everything else alone. The user stays signed in to the auth server, and your app’s other grants and other apps keep working. To sign the user out of the auth server too, send them to the logout endpoint. See Sign users out.
An API that checks access tokens by their signature alone accepts them until they expire, so keep access tokens short-lived. An API that introspects them sees them inactive at once.
An access token from the client credentials grant or the implicit flow belongs to no grant. Revoking it ends that token alone, at /userinfo, the auth server’s APIs and the introspection endpoint.
The request
Section titled “The request”/auth/revoke takes a POST, with the parameters in an application/x-www-form-urlencoded body. Each parameter goes in once.
| Parameter | Required | What it does |
|---|---|---|
token |
Yes | A refresh token or an access token the auth server issued to your client |
token_type_hint |
No | Ignored. The auth server reads the token’s type from the token |
Client authentication
Section titled “Client authentication”A confidential client authenticates exactly as at the token endpoint, with client_secret_basic or client_secret_post. See Client authentication for the rules and the refusals, which are the same here.
A public client, such as a single-page app or a mobile app, sends its client_id in the body and no secret.
The auth server’s log has a client authentication refused at the revocation endpoint warning for each refusal. See Logs.
The answer
Section titled “The answer”| Status | When |
|---|---|
200 OK, empty body |
The grant or the token was revoked, or the token was invalid already: expired, revoked, unknown, malformed, an ID token, or one the auth server doesn’t accept any more. Either way, your app can delete it |
400 Bad Request, invalid_grant |
The token is live and was issued to another client: “The token was issued to another client.” Nothing is revoked |
400 Bad Request, invalid_request |
token or client_id is missing, a parameter or the Authorization header is repeated, the body can’t be read, the secret is sent both ways, or a public client sent a secret |
401 Unauthorized, invalid_client |
The client couldn’t be authenticated |
503 Service Unavailable, temporarily_unavailable |
The auth server couldn’t check or revoke the token, or couldn’t confirm it did. Treat the token as still working, and try again later |
An error is a JSON body with error and error_description, as on the token endpoint.
Calling it from a browser
Section titled “Calling it from a browser”JavaScript in a browser can call the revocation endpoint when its origin is registered as a web origin on a client, as for the token endpoint.