Tyler Pinho

What’s the Problem We’re Solving?

OAuth is the de facto standard for authorization, and it’s used just about everywhere. You’ve probably used it without even realizing it—like when you log into an app using your Google or Facebook account. OAuth works by issuing tokens (usually JWTs, or JSON Web Tokens) that represent a user’s permissions. These tokens are then sent to APIs who will then confirm the token with the Identity Server prior to allowing the user to access or modify resources.

Most web developers will, without a second thought, store this token on the frontend for all pages to use to send secure requests to the backend APIs. However, JWTs can contain sensitive information. For example, they might include user roles, IDs, email addresses, or other claims that you don’t want to expose to the client (like a browser or mobile app). If this is stored in plain text on the frontend, a malicious actor could engage in credential stuffing, impersonating users, and even stealing JWTs. At the same time, APIs need this information to make authorization decisions. So, how do we keep sensitive data secure while still making it available to the right parties?

Enter Phantom Token Architecture.

What Is Phantom Token Architecture?

Phantom Token Architecture is a way to effectively split the token into two parts:

A reference token (opaque token) for use on the client.
A JWT for use on the API.

Here’s how it works:

The client gets a reference token. When a user logs in, the Identity Server issues a reference token to the client. This token is just a random string—it doesn’t contain any sensitive data. Think of it as a ticket stub that says, “Hey, I’m allowed to be here, but you’ll need to check with the bouncer for details.”
The client sends the reference token to the API. The client includes the reference token in the Authorization header of its API requests. At this point, the API doesn’t know anything about the user—it just sees the reference token.
The API exchanges the reference token for a JWT. Here’s where the magic happens. The API sends the reference token to the Identity Server (or a token introspection endpoint) and asks, “Hey, what’s the real deal with this token?” The Identity Server responds with a JWT that contains all the juicy details—like user roles, permissions, and other claims.
The API uses the JWT to authorize the request. Now that the API has the JWT, it can make informed decisions about whether to allow the request. For example, it might check if the user has the right role to access a specific resource.

When Should You Consider Using Phantom Tokens?

This pattern shines in scenarios where:

You have untrusted clients (like browsers or mobile apps).
You need to protect sensitive information in JWTs (e.g. UserIDs, Email, etc).
You have publicly accessible APIs or UIs.
You want to centralize token validation and introspection.

It’s particularly useful in microservices architectures, where APIs need to make fast, secure authorization decisions without exposing sensitive data to clients.

High Level Example

Let’s say you’re building a web app that lets users view their order history. Here’s how Phantom Token Architecture might play out:

The user logs in, and the Identity Server issues a reference token to the browser.
The browser sends the reference token to the Orders API.
The Orders API sends the reference token to the Identity Server and gets back a JWT with the user’s ID and roles.
The Orders API checks the JWT to ensure the user has permission to view their order history, then returns the data.

The browser never sees the JWT, and the API gets all the info it needs. Everyone’s happy!

Code Implementation

Let’s dive into some code to see how Phantom Token Architecture works in practice. We’ll use Node.js and Express for simplicity, but the concepts apply to any stack.

For a working code solution, download the source code project from my github.

1. Identity Server: Issuing Tokens

The Identity Server is responsible for issuing both the reference token and the JWT. Here’s a simplified example:


const express = require('express');
const jwt = require('jsonwebtoken');
const app = express();

app.use(express.json());

// In-memory store for reference tokens and their corresponding JWTs
const tokenStore = new Map();

// Endpoint to issue tokens
app.post('/oauth/token', (req, res) => {
  const { client_id, client_secret } = req.body;

  // Validate client credentials (simplified for example)
  if (client_id !== 'my-client' || client_secret !== 'my-secret') {
    return res.status(401).json({ error: 'Invalid client credentials' });
  }

  // Create a reference token (random string)
  const referenceToken = Math.random().toString(36).substring(2);

  // Create a JWT with user claims
  const jwtToken = jwt.sign(
    { userId: 123, roles: ['user'] }, // Payload
    'my-secret-key',                 // Secret key
    { expiresIn: '1h' }              // Expiration
  );

  // Store the reference token and JWT mapping
  tokenStore.set(referenceToken, jwtToken);

  // Return the reference token to the client
  res.json({ access_token: referenceToken, token_type: 'Bearer' });
});

// Endpoint to exchange reference token for JWT
app.post('/oauth/introspect', (req, res) => {
  const { token } = req.body;

  // Look up the JWT for the given reference token
  const jwtToken = tokenStore.get(token);

  if (!jwtToken) {
    return res.status(401).json({ error: 'Invalid token' });
  }

  // Return the JWT to the API
  res.json({ jwt: jwtToken });
});

app.listen(3000, () => console.log('Identity Server running on port 3000'));

2. Client: Using the Reference Token

The client receives the reference token and uses it to call the API. Here’s an example of a client app:


const axios = require('axios');

// Get a reference token from the Identity Server
const getReferenceToken = async () => {
  const response = await axios.post('http://localhost:3000/oauth/token', {
    client_id: 'my-client',
    client_secret: 'my-secret',
  });

  return response.data.access_token;
};

// Call the API with the reference token
const callApi = async () => {
  const referenceToken = await getReferenceToken();

  try {
    const apiResponse = await axios.get('http://localhost:4000/orders', {
      headers: {
        Authorization: `Bearer ${referenceToken}`,
      },
    });

    console.log('API Response:', apiResponse.data);
  } catch (error) {
    console.error('API Error:', error.response.data);
  }
};

callApi();

3. API: Exchanging Reference Token for JWT

The API receives the reference token, exchanges it for a JWT, and uses the JWT to authorize the request:


const express = require('express');
const axios = require('axios');
const jwt = require('jsonwebtoken');
const app = express();

app.use(express.json());

// Middleware to validate the reference token and get the JWT
const validateToken = async (req, res, next) => {
  const authHeader = req.headers.authorization;

  if (!authHeader || !authHeader.startsWith('Bearer ')) {
    return res.status(401).json({ error: 'Unauthorized' });
  }

  const referenceToken = authHeader.split(' ')[1];

  try {
    // Exchange reference token for JWT
    const response = await axios.post('http://localhost:3000/oauth/introspect', {
      token: referenceToken,
    });

    // Attach the JWT to the request object
    req.jwt = response.data.jwt;
    next();
  } catch (error) {
    res.status(401).json({ error: 'Invalid token' });
  }
};

// Example protected endpoint
app.get('/orders', validateToken, (req, res) => {
  // Decode the JWT to get user claims
  const decoded = jwt.verify(req.jwt, 'my-secret-key');

  // Check user roles or other claims
  if (!decoded.roles.includes('user')) {
    return res.status(403).json({ error: 'Forbidden' });
  }

  // Return some data
  res.json({ orders: [{ id: 1, item: 'Product A' }] });
});

app.listen(4000, () => console.log('API running on port 4000'));

How It All Works Together

The client gets a reference token from the Identity Server.
The client sends the reference token to the API.
The API exchanges the reference token for a JWT by calling the Identity Server’s introspection endpoint.
The API uses the JWT to authorize the request and return the appropriate data.

Tools You Can Use

If you’re building this in a real-world scenario, consider using these established libraries and services:

Identity Server: Duende, Auth0, or Okta.
JWT Libraries: jsonwebtoken for Node.js, or equivalent libraries for your stack.

Other Security Enhancements

While making the client side token opaque does improve your security posture there are still other enhancements a corporation or larger website may want to pursue:

Add Cloudflare to Identity Server. Rate limiting the introspection and token provisioning endpoints will reduce the effectiveness of credential stuffing and other malicious attacks intended to uncover user JWTs.
Implement Refresh Token. Refresh Tokens are a great tool for allowing you to reduce the lifecycle of the reference token or JWT by having a longer running refresh token to maintain the session. This ensures that even if the reference token is leaked a malicious actor would only have a short frame to work with (e.g. 5 min vs 1 day).
Make Client Tokens Http Only. The inclination of developers is to store tokens within the cookies via the frontend after receiving the tokens from the Identity Server. However, its a more secure practice to have the Identity Server or another backend send the cookie down as Http Only. This allows the frontend to use it without modifcation or accessing outside of HTTP.

Wrapping Up

Phantom Token Architecture is a good way to balance security and simplicity in OAuth-based systems. By splitting tokens into reference tokens and JWTs, it keeps sensitive data safe while giving APIs the information they need to make authorization decisions.

If you’re working on a system that needs to handle sensitive user data or untrusted clients, this pattern is definitely worth considering.