Token revocation

Tokens expire on their own; revocation is the way to expire them early. RFC 7009 is the standard for it.

You use revocation when the user signs out, when a device is reported lost, when a refresh token is suspected of being leaked, or any other time the user-facing event of "this credential should stop working now" needs to happen.

The call

POST https://<your-tenant-url>/oauth2/revoke
Content-Type: application/x-www-form-urlencoded

token=<the-token-to-revoke>
&token_type_hint=refresh_token         # or access_token; optional but recommended
&client_id=<your-client-id>

Responses follow RFC 7009: the platform returns 200 OK whether the token existed and was revoked, or didn't exist at all. This is deliberate — the response intentionally doesn't tell the caller whether a guess was correct. Treat any 200 as success.

400 Bad Request indicates the call itself was malformed (missing token, missing client_id, etc.).

What revocation actually does

Revoking an access token invalidates the single token. Other tokens issued from the same session are untouched.
Revoking a refresh token invalidates the refresh token and the entire family of access tokens descended from it. The next refresh attempt fails.

For a clean sign-out, revoke the refresh token. The access token will expire on its own within minutes; revoking it separately is only worthwhile if you have a specific reason to kill it sooner than its exp.

Sign-out, end to end

async function signOut() {
  const refresh = getStoredRefreshToken()
  if (refresh) {
    await fetch(`${tenantUrl}/oauth2/revoke`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
      body: new URLSearchParams({
        token: refresh,
        token_type_hint: 'refresh_token',
        client_id,
      }),
    })
  }
  clearLocalState()  // remove cookies, redirect to /goodbye, etc.
}

The SDK does this for you when you call logout(). The above is the bare wire format for non-SDK clients.

What revocation does NOT do

It does not log the user out of other applications that share the same identity provider. If you want to sign the user out of every application connected to their identity, the right endpoint is the platform's logout endpoint, not revocation.
It does not kill the user's tenant session itself. Sessions are a separate concept from OAuth tokens. To end the session as well, redirect the user through the logout endpoint.
It does not invalidate already-validated audit entries. Audit log entries are immutable; revocation does not retroactively annotate them.

Revoking somebody else's tokens (admin sign-out)

The grant above is for self-revocation. To revoke a token you do not hold — say, an administrator forcibly signing a user out across all their devices — use the admin session-management surface in the tenant admin console. The audit log records both the revocation and the administrator who triggered it.

Revocation propagation

Revocation hits the platform's token introspection layer immediately. APIs that introspect every token (the strict pattern) see the change on the very next call. APIs that locally validate JWTs (the cheap pattern) keep accepting the revoked access token until its exp claim. The latter is why short access-token lifetimes matter — a leaked access token's danger window is bounded by exp, not by revocation.

If your API needs immediate revocation effect, introspect tokens (call /oauth2/introspect or check a revocation cache) rather than relying on JWT signature alone.