---
title: "Implementing the Phantom Token Approach Using OAuth Introspection"
description: "A step-by-step tutorial describing how to configure the Curity Identity Server to use the phantom token pattern"
url: "https://curity.io/resources/learn/introspect-with-phantom-token/"
date: "2025-03-17"
area: "tutorials"
topic: "howtos"
pagegroup: "phantom-token-integration"
---

# Implementing the Phantom Token Approach Using OAuth Introspection

In most deployments, organizations should use reference tokens (opaque tokens) outside the internal network and then JSON Web Tokens (JWTs) within it. The phantom token approach allows for achieving this goal. You can find a detailed description of this pattern in the [phantom token pattern](https://curity.io/resources/learn/phantom-token-pattern/) article. This tutorial describes how to set up the Curity Identity Server for phantom tokens.

The pattern assumes that the system uses a single entrypoint to the internal network — an API gateway, sometimes called an API firewall or a reverse proxy. When the gateway receives a request with an opaque token it exchanges the token at the authorization server for a JWT. In an overview, the phantom token pattern looks like this:

![An overview of the phantom token pattern showing how an API gateway exchanges an opaque token for a JWT before sending it APIs](https://curity.io/images/resources/operate/tutorials/integration/introspect-with-phantom-token/introspect-with-phantom-token.svg) 

This tutorial focuses on configuring the authorization server so that it can play its part in the pattern and exchange a reference token for a JWT. If you want to learn how to implement the pattern in a gateway, then have a look at the [phantom token integrations](https://curity.io/resources/phantom-token-integration/) page. There you will find tutorials that show how to implement the pattern in various gateways.

The authorization server can leverage the [introspection endpoint](https://www.rfc-editor.org/rfc/rfc7662) to implement the pattern. The introspection response contains metadata associated with an access token, which in the Curity Identity Server translates to claims. By default, the result of an introspection is an unsigned JSON document. This means that you have to tweak the introspection behavior, so that the authorization server returns a signed JWT, which the API gateway can pass on to downstream APIs.

## Preparing the Curity Identity Server

There are two ways of using the pattern in the Curity Identity Server. The Curity Identity Server can either:

-   return only a JWT as a response from the introspection endpoint (the `application/jwt` approach), or
-   return the JWT additionally to all the other claims normally returned by the introspection (the `token procedure` approach).

If the API gateway does not require any information about the received access token, other than whether the token is valid, then use the `application/jwt` approach. If the API gateway needs to act on the contents of the token, and is not able to easily decode the JWT, then we recommend the `token procedure` approach.

In either case, first ensure that the Curity Identity Server exposes the introspection endpoint. The next section explains how to do it.

### Enable the Introspection Endpoint

This tutorial assumes that you have a working instance of the Curity Identity Server, configured at least with the basic configuration wizard. Furthermore, the tutorial assumes that there is a token profile called `token-service` and a service role called `default`. If you need to quickly set up an instance of the Curity Identity Server, then have a look at the [getting started](https://curity.io/resources/getting-started/) guides.

Using the Example Configuration

If you're using the [example configuration](https://developer.curity.io/release/latest/configuration-samples), you can skip this part. Your deployment already exposes the introspection endpoint and has a default signing key. You will also have a client called `gateway-client` that has the introspection capability. Skip ahead to [Enabling Phantom Tokens](https://curity.io/resources/learn/introspect-with-phantom-token/#enabling-phantom-tokens).

To enable the introspection endpoint, complete these steps:

1.  Allow the introspection capability on the profile
2.  Add the introspection endpoint to the token profile if necessary
3.  Publish the introspection endpoint on the service profile

You can follow these steps either from the admin UI or by typing commands using a Command Line Interface.

**Using the Admin UI**

Use the admin UI Expert mode

When following the steps in the Curity Identity Server, make sure that you are using the **Expert** mode of the admin UI. The admin UI uses the **Expert** mode by default, so remember to switch it back if you previously changed to the **Normal** mode. You can find more information about the modes in [this overview](https://curity.io/resources/learn/first-config/#switch-to-the-normal-mode).

Go to **Profiles** → **Token Service** → **General** → **Client Settings**. Enable the **Introspection** capability, as the screenshot below shows:

![List of a token service capabilities with the introspection capability enabled](https://curity.io/images/resources/operate/tutorials/integration/introspect-with-phantom-token/client-capabilities.jpg)

Next, go to **Profiles** → **Token Service** → **Endpoints**. If the endpoint with the type `oauth-introspect` doesn't exist, click `+ New Endpoint` to create a new one. Give it a name and choose a path, e.g., `/oauth/v2/oauth-introspect`, then select `oauth-introspect` from the **Endpoint Type** dropdown. Click **Create**. The filled-in endpoint form should look similar to this:

![Filled-in new endpoint form](https://curity.io/images/resources/operate/tutorials/integration/introspect-with-phantom-token/add-new-endpoint.jpg)

You will see the newly added endpoint on the list of endpoints with a red **Not Deployed** button, as the following screenshot shows:

![An excerpt from the list of endpoints which shows the newly added endpoint marked as not deployed](https://curity.io/images/resources/operate/tutorials/integration/introspect-with-phantom-token/introspect-endpoint.jpg)

Click the button and select the `default` service role, then click **OK**. Finally, save the changes by selecting **Commit** from the **Changes** menu at the top.

**Using the CLI**

Open the terminal on the machine that is running the Curity Identity Server. If you run the Curity Identity Server in a local container connect to the container's terminal. If you are working with a remote instance of the Curity Identity Server make sure to use the CLI mode on the admin node.

From the terminal, type the following command to start the configuration CLI.

```shell
$IDSVR_HOME/bin/idsh
```

If you're running the Curity Identity Server from an official container, then `$IDSVR_HOME` will resolve to `/opt/idsvr`. If you're running a local instance and you don't have `$IDSVR_HOME` set, simply run the `idsh` command from the `bin` folder of the Curity Identity Server installation directory.

In the admin CLI, type the following commands to enable introspection capability and to deploy the introspection endpoint under the path `/oauth/v2/oauth-introspect`.

```shell
configure
set profiles profile token-service oauth-service settings authorization-server client-capabilities introspection
set profiles profile token-service oauth-service endpoints endpoint introspect endpoint-kind oauth-introspect uri /oauth/v2/oauth-introspect
set environments environment services service-role default endpoints introspect
commit
```

Now the endpoint is set and active on the nodes that have the `default` service role. Next, ensure that the system has a JWT issuer with a signing key assigned.

### Enable JWT Issuance

Use the following steps to check if there is a JWT issuer in the system and that it has a signing key.

**Using the Admin UI**

Go to **Profiles** → **Token Service** → **Token Issuers**. Ensure that `Enable JSON Web Tokens` is toggled on and that there is a key assigned in the **Signing Key** field. The following screenshot shows the `default-signing-key` assigned to the token issuer:

![Token Issuers form that shows the default-signing-key assigned to the JWT issuer](https://curity.io/images/resources/operate/tutorials/integration/introspect-with-phantom-token/token-issuer-with-signing-key.jpg)

**Using the CLI**

In the admin CLI, type the following commands.

```shell
show profiles profile token-service oauth-service token-issuers default-token-issuer jwt-issuer-settings signing-key-id
```

The output of the command should be similar to the following one, which indicates that the default JWT issuer has an assigned signing key:

```shell
signing-key-id default-signing-key;
[ok][2025-03-05 13:50:40]

[edit]
```

If you don't have a signing key, follow the instructions in this section.

**Using the Admin UI**

Open the **Facilities** menu in the top right corner and go to **Keys and Cryptography** → **Signing** → **Signing Keys**. Click the **+** button to add a new key pair. Give the key a name, choose the `asymmetric` type, and select `Generate New`. Choose a **Key Type**. We recommend to use an `eddsa` key, but you have to ensure that your APIs are able to verify signatures created with this algorithm. Fill in the required fields then click **Create & Commit**. The key creation form will look similar to this screen:

![Filled-in form for creating a new EdDSA signing key](https://curity.io/images/resources/operate/tutorials/integration/introspect-with-phantom-token/create-new-signing-key.jpg)

**Using the CLI**

To add a signing key using the CLI, first, prepare a keystore, then insert it into the configuration of the Curity Identity Server. Have a look at [Configuring private keystores](https://curity.io/docs/identity-server/facilities/cryptography/keystores/configuring-private-keystores/) in the documentation to learn how to add keystores using the CLI. Once yo have a keystore in a correct format, as described in the documentation, use the following command to add it to the configuration (the command uses `default-signing-key` as the keystore ID:

```bash
request facilities crypto add-signing-key-keystore id default-signing-key
```

Next, create an OAuth client that will be able to perform the introspection.

### Configure Client for Introspection

In the phantom token pattern, the API gateway or the reverse proxy needs an OAuth client to introspect incoming access tokens. Create a dedicated client for that purpose. Set up such a client with only the introspection capability, so that it cannot perform any other OAuth requests.

**Using the Admin UI**

In the admin UI go to **Profiles** → **Token Service** → **Clients** and click on **\+ New Client**. Give the client an ID, e.g. `gateway-client`, as the following screenshot shows. Then, click **Create**.

![Form for creating a new client with the ID filled-in](https://curity.io/images/resources/operate/tutorials/integration/introspect-with-phantom-token/create-new-client.jpg)

Scroll down to **Capabilities** and click **Add capabilities**. Select only the introspection capability as the screenshot below shows. Then, click **Next**.

![Form showing available client capabilities with introspection selected](https://curity.io/images/resources/operate/tutorials/integration/introspect-with-phantom-token/introspection-capability.jpg)

From the **Authentication Method** choose `secret` and enter a client secret, e.g. `Password1`. After clicking **Next** you will see a reminder to copy the client secret, as on this screen:

![Form for setting client authentication with configured client secret](https://curity.io/images/resources/operate/tutorials/integration/introspect-with-phantom-token/client-authentication.jpg)

Click **Next** once more. Save changes by selecting **Commit** from the **Changes** menu at the top.

**Using the CLI**

In the admin CLI, type the following commands. This will create an OAuth client with the ID `gateway-client`. The client will have only the introspection capability enabled and will use a client secret (`Password1`) for authentication. You can adjust the client ID and secret to suit your needs.

```shell
configure
edit profiles profile token-service oauth-service settings authorization-server client-store config-backed
set client gateway-client capabilities introspection
set client gateway-client secret Password1
commit
```

The Curity Identity Server has now all the configuration you need to enable phantom tokens.

## Enabling Phantom Tokens

This tutorial mentions two ways of implementing phantom tokens in the Curity Identity Server. For testing purposes, you can try to implement both ways. In a production environment, you will normally need to only use one of them. Let's start with the simpler approach.

### Application/JWT Approach

The `application/jwt` approach is the simpler way of the two options. In this approach, the gateway receives only the JWT that corresponds with the opaque token. You will usually use it in setups where the gateway does not need to operate on the token's claims — the gateway will simply forward the request with a JWT, if the token is valid.

This approach does not require any additional setup. Enable it by setting a special value in the `Accept` header of the introspection request. When the request has an `Accept: application/jwt` request header, the Curity Identity Server will respond with the JWT version of the incoming token.

Here is a curl example of an introspection request from the previously created `gateway-client`. The example uses this opaque token: `ba06557a-c2b6-439e-85a0-759c8e953e14` and assumes that the instance of the Curity Identity Server runs on `https://localhost:8443`.

```shell
curl -X POST \
  https://localhost:8443/oauth/v2/oauth-introspect \
  -H 'accept: application/jwt' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'token=ba06557a-c2b6-439e-85a0-759c8e953e14&client_id=gateway-client&client_secret=Password1'
```

Instead of the full JSON response, the Curity Identity Server responds with the JWT directly in the response body, similar to the following:

```shell
eyJraWQiOiItMzgwNzQ4MTIiLCJ4NXQiOiJNUi1wR1RhODY2UmRaTGpONlZ3cmZheT....LJHlj1Og
```

The gateway then copies the JWT to the `Authorization` header of the original request and forwards it to the API.

### Token Procedure Approach

Sometimes the API gateway or a reverse proxy needs information from the token to make its own decisions. If you use the `apllication/jwt` approach, the gateway can decode the JWT and read the token's claims, but sometimes it might be inconvenient to do it in the gateway. For such situations you can use the token procedure approach in which you combine the regular introspection response with a phantom token.

To implement this approach, add a token procedure to the introspection endpoint. Follow these steps to implement the token procedure approach.

**Using the Admin UI**

In the admin UI go to **Profiles** → **Token Service** → **Endpoints**. Click on the introspection endpoint. In the **Introspect** drop-down, select `+ New procedure`, give it a name, e.g. `phantom-token-procedure`. The edit endpoint form should look similar to this screenshot:

![Endpoint edit form with new token procedure being added to the introspect flow](https://curity.io/images/resources/operate/tutorials/integration/introspect-with-phantom-token/add-new-procedure-to-endpoint.jpg)

Click `Save`. An editor pop-up window will open. Replace the default script with the following:

```javascript
/**
 * @param {se.curity.identityserver.procedures.context.IntrospectionTokenProcedureContext} context
 */
function result(context) {
    var responseData = {
        active: context.presentedToken.active
    };

    if (context.presentedToken.active) {
        appendObjectTo(context.presentedToken.data, responseData);
        responseData.token_type = context.presentedToken.type;
        responseData.client_id = context.presentedToken.delegation.clientId;
        responseData.expired_scope = context.presentedToken.expiredScopes;

        var defaultAtJwtIssuer = context.getDefaultAccessTokenJwtIssuer();
        responseData.phantom_token = defaultAtJwtIssuer.issue(context.presentedToken.data,
            context.delegation);
    }

    return responseData;
}
```

The only change from the default procedure is in the highlighted lines. This additional code gets the `defaultAtJwtIssuer` from the procedure context and uses it to create a new JWT access token based on the `presentedToken`. Then, the procedure adds the JWT to the response in a `phantom_token` field.

Click **Update**, then **Close**. Close the endpoint edit form, then save changes by choosing **Commit** from the **Changes** menu at the top.

**Using the CLI**

First, encode the Javascript procedure in base64. Type the following command in a terminal:

```shell
echo '/**
* @param {se.curity.identityserver.procedures.context.IntrospectionTokenProcedureContext} context
*/
function result(context) {
    var responseData = {
        active: context.presentedToken.active
    };

    if (context.presentedToken.active) {
        appendObjectTo(context.presentedToken.data, responseData);
        responseData.token_type = context.presentedToken.type;
        responseData.client_id = context.presentedToken.delegation.clientId;
        responseData.expired_scope = context.presentedToken.expiredScopes;

        var defaultAtJwtIssuer = context.getDefaultAccessTokenJwtIssuer();
        responseData.phantom_token = defaultAtJwtIssuer.issue(context.presentedToken.data,
        context.delegation);
    }

return responseData;
}' | base64
```

The procedure is a slight variation from a default token procedure and you can see the changes in the highlighted lines. This additional code gets the `defaultAtJwtIssuer` from the procedure context and uses it to create a new JWT access token based on the `presentedToken`. Then, the procedure adds the JWT to the response in a `phantom_token` field.

Copy the command result, then, in the admin CLI type the following commands. At the end of the first command paste the base64-encoded script. The command will create a procedure with the name `phantom-token-procedure`, then assign the procedure to the introspection endpoint.

```shell
set processing procedures token-procedure phantom-token-procedure oauth-introspect script paste_base64_encoded_script_here
set profiles profile token-service oauth-service endpoints endpoint token-service-introspect introspect-endpoint-procedures oauth-introspect procedure phantom-token-procedure
commit
```

Here is a curl example of an introspection request from the previously created `gateway-client`. The example uses this opaque token: `ba06557a-c2b6-439e-85a0-759c8e953e14` and assumes that the instance of the Curity Identity Server runs on `https://localhost:8443`.

```shell
curl -X POST \
  https://localhost:8443/oauth/v2/oauth-introspect \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'token=ba06557a-c2b6-439e-85a0-759c8e953e14&client_id=gateway-client&client_secret=Password1'
```

If you use a valid opaque token you should see a response similar to the following one. You can see the phantom token in the highlighted line.

```json
{
    "sub": "demouser",
    "purpose": "access_token",
    "iss": "https://localhost:8443/oauth/v2/oauth-anonymous",
    "active": true,
    "token_type": "bearer",
    "client_id": "server-client",
    "aud": "https://api.demo.example",
    "nbf": 1512642625,
    "scope": "read",
    "expired_scope": [],
    "exp": 1512642925,
    "delegationId": "aca9436d-fefc-4aaa-8385-fbcb6a7847be",
    "iat": 1512642677,
    "phantom_token": "eyJraWQiOiIxNTQzMTE2MDE1I..."
}
```

## Testing the Implementation

To test the implementation, you need to obtain an opaque access token, which you will exchange for a JWT. To do that, first run a code flow against the Curity Identity Server. You have two options to do that:

-   You can test [using OAuth tools](https://curity.io/resources/learn/test-using-oauth-tools/)(recommended).
-   You can also follow the [code flow](https://curity.io/resources/learn/code-flow/) tutorial to run the flow using a browser and curl.

To run the test, you need a client capable of running the code flow and at least one authenticator. You can follow the tutorials in the [getting started guides](https://curity.io/resources/getting-started/) if you need to configure these.

Once you complete an OAuth flow and get an opaque access token you can use it to make a curl request to the introspection endpoint. The Curity Identity Server will respond accordingly to the approach you implemented and to the value of the request's `Accept` header.

If you want to test an end-to-end flow with an API gateway that performs the translation, then have a look at the tutorials in the [phantom token integration](https://curity.io/resources/phantom-token-integration/) section. You will find tutorials that show how to implement the pattern in concrete gateways. For example, the [NGINX phantom token module](https://curity.io/resources/learn/nginx-phantom-token-module/) tutorial uses the NGINX reverse proxy and the [Curity phantom token module](https://github.com/curityio/nginx_phantom_token_module) to implement the pattern.
