How toUse the OAuth2 Introspection Endpoint

When you use opaque access tokens in OAuth2, your API can’t validate them locally. Unlike JWTs, opaque tokens don’t carry their own claims or signature—they’re just random strings.

That means your API needs to call the introspection endpoint of the authorization server to verify the token and get information about the user or scopes.

The introspection endpoint returns a JSON object with metadata about the token:

  • active: whether the token is valid and active
  • scope: a space-separated list of scopes
  • username: the user ID or login name
  • exp: the expiration time (Unix timestamp)
  • client_id: the client that requested the token

Here’s how to call the introspection endpoint and handle the response:

let res = await fetch(new URL("/introspect", issuer), {
  method: "POST",
  headers: {
    Authorization: `Basic ${btoa(clientId + ":" + clientSecret)}`,
    "Content-Type": "application/x-www-form-urlencoded",
  },
  body: new URLSearchParams({ token }),
});

let data = await res.json();
if (!data.active) throw new Error("Invalid token");

let scopes = data.scope?.split(" ");
let userId = data.username;

If the token is active, you can use its metadata to authorize the request—check the scopes, identify the user, etc.

If not, reject the request right away.

This and much more is covered in the book I’m writing about OAuth2 for modern web apps, using React Router and Remix as the reference framework.

Check it out at books.sergiodxa.com