Implementing Token Introspection

In this lesson, you will learn how to verify an access token’s validity in real-time by querying an Authorization Server, ensuring you don't rely solely on the potentially outdated information inside a JWT.

Why Introspection?

Previously, we discussed stateless JWT validation, where your resource server checks the signature and expiration time locally. However, if a user logs out or an administrator revokes a token before it expires, the resource server remains unaware because the token's signature is still mathematically "valid."

Token Introspection (defined in RFC 7662) allows your resource server to act as a client and send the token to the Authorization Server’s /introspect endpoint. The server responds with the actual status of that token, confirming whether it is active: true and providing the latest metadata, such as current scopes or associated user IDs.

Implementation Pattern

When your Node.js application receives a request with an Authorization: Bearer <token> header, instead of just decoding it, you perform a server-to-server request:

const axios = require('axios');

async function introspectToken(token) {
  try {
    const response = await axios.post(process.env.INTROSPECTION_URL, {
      token: token
    }, {
      headers: {
        'Authorization': `Basic ${Buffer.from(CLIENT_ID + ':' + CLIENT_SECRET).toString('base64')}`
      }
    });

    if (response.data.active === true) {
      return response.data; // Token is valid, return identity info
    }
    throw new Error('Token is inactive');
  } catch (error) {
    throw new Error('Introspection failed');
  }
}

Strategic Trade-offs

While introspection provides the highest level of security and near-instant revocation, it introduces a network round-trip for every request. In a high-traffic environment, this can create latency or bottleneck your Authorization Server. To mitigate this, developers often use introspection to check the status of sensitive operations, or cache the "introspected" result for a very short duration (e.g., 30–60 seconds) to balance performance with security.

By combining local JWT validation (for speed) with periodic or conditional introspection (for security), you build a robust identity verification layer that respects both performance and revocation state.

Key Takeaway: Token Introspection offloads the burden of truth to the Authorization Server, allowing you to invalidate sessions in real-time even if your access tokens are cryptographically valid.