---
title: "Integrating With Tyk Self-Managed Using the Phantom Token Pattern"
description: "How to configure Tyk to use a rich gRPC plugin to implement the Phantom Token pattern"
url: "https://curity.io/resources/learn/integration-tyk-self-managed-phantom-token/"
date: "2025-10-29"
area: "tutorials"
topic: "howtos"
pagegroup: "phantom-token-integration"
repository: "https://github.com/curityio/tyk-phantom-token-plugin"
---

# Integrating With Tyk Self-Managed Using the Phantom Token Pattern

Tyk Self-Managed offers a plethora of options when it comes to extending the capability of the API gateway. A powerful option is to use a so-called rich plugin. This approach allows the plugin to be written in any language that supports [gRPC](https://grpc.io/docs/what-is-grpc/introduction/). The plugin is deployed as a separate service and can be invoked by Tyk during different phases of both the request and response flows.

## Plugin Overview

The plugin is comprised of 2 separate services, a plugin bundle and the actual plugin service itself. The plugin bundle is a signed manifest exposed as `phantom-bundle.zip` that tells Tyk how to wire in the plugin service. It defines that the plugin driver is gRPC and which hooks should be executed, e.g. where in the request/response flow of Tyk the plugin should be invoked. The plugin service implements the actual logic of the plugin, in this case the phantom token pattern.

![Tyk Phantom Token Plugin Overview](https://curity.io/images/resources/howtos/gateway/tyk-self-managed/tyk-phantom-token.svg)

## Configure the Curity Identity Server

The Curity Identity Server needs to be set up to handle introspection. This is the case by default but review the configuration of the system in use before continuing and make sure you have a [Client configured for introspection](https://curity.io/resources/learn/introspect-with-phantom-token/#configure-client-for-introspection).

This article assumes that the Curity Identity Server is set up to handle the `application/jwt` approach of introspection as outlined in the [OAuth Introspection and Phantom Tokens](https://curity.io/resources/learn/introspect-with-phantom-token/) article.

## Build and Run the Plugin

The plugin is available as a Docker compose project and is easy to get running:

1.  Clone the repository linked at the top of this tutorial
2.  Set the .env variables needed (Introspection URL, client\_id and client\_secret)
3.  Build and run the docker compose project by executing:

```sh
docker compose up -d --build
```

This starts the 2 services described above, `bundle-server` and `phantom-plugin`.

## Configure Tyk Self-Managed

If you don't have an installation of [Tyk Self-Managed](https://tyk.io/self-managed/) up and running already, refer to the [Tyk Quick Start Guide](https://tyk.io/docs/getting-started/quick-start/) to get going.

### Tyk Configuration

You need to configure the Tyk Gateway to allow the use of gRPC plugins and define the location of the plugin bundle. You configure this in the `tyk.conf` file. The configuration might look similar to this:

```yml
{
  "listen_port": 8080,
  "secret": "352d20ee67be67f6340b4c0605b044b7",

  "enable_coprocess": true,
  "coprocess_options": {
    "enable_coprocess": true,
    "coprocess_grpc_server": "tcp://phantom-plugin:50051"
  },

  "enable_bundle_downloader": true,
  "bundle_base_url": "http://bundle-server/",

  "use_db_app_configs": true,
  "db_app_conf_options": {
    "connection_string": "http://tyk-dashboard:3000",
    "node_is_segmented": false,
    "enable_app_key_hashing": false,
    "use_app_id_as_key": true
  },

  "storage": { "type": "redis", "host": "tyk-redis", "port": 6379 },
  "log_level": "debug"
}
```

### Tyk Dashboard

Configure the API in Tyk to:

-   Enable **Authentication**
-   Set the type to `Custom Plugin`
-   Set the **Authentication token location** to `Authorization` header
-   Leave the **Enable plugin Config** `Off`.

![Enable API Authentication](https://curity.io/images/resources/howtos/gateway/tyk-self-managed/tyk-enable-auth.jpg)

Scroll down to the **Plugin configuration** section:

-   Make sure **Config data** is `Off`
-   Set the **Plugin driver** to `gRPC`
-   Enable **Plugin bundle**
-   Set the **Bundle filename** to `phantom-bundle.zip`. The is the file that the bundle service exposes to the Tyk gateway

![Configure Plugin](https://curity.io/images/resources/howtos/gateway/tyk-self-managed/tyk-plugin-config.jpg)

## Test Using OAuth Tools

1.  In [OAuth Tools](https://oauth.tools/?utm_source=curity.io&utm_medium=Link&utm_content={props.utmContent}), create a flow to obtain an Access Token. Review the [Test using OAuth Tools](https://curity.io/resources/learn/test-using-oauth-tools/) article for more details.
2.  Create a **Call External API** flow. Enter the URL of the API exposed by the Tyk Self Managed API gateway. Configure the method according to what’s possible with the API. Select the token retrieved in the previous step from the drop-down list and click **Send**.

![Obtain Access Token](https://curity.io/images/resources/howtos/gateway/tyk-self-managed/tyk-obtain-at.jpg)

![Call Tyk Gateway](https://curity.io/images/resources/howtos/gateway/tyk-self-managed/tyk-call-api.jpg)

The opaque access token is sent in the API request to Tyk. In the screenshot above the backend API is [Httpbin](https://httpbin.org/) which echoes back the request details it receives. So even though the opaque token was sent in the `Authorization` header, a JWT was echoed back showing that the backend API does get the JWT.

## Access Token Expiry

When you use the phantom token plugin, access token expiry responses can originate either from upstream APIs or the plugin itself. In either case, clients receive an HTTP `401` response and can deal with that condition resiliently. Typically, the client runs a token refresh operation and retries the API request with a new access token. To ensure the correct expiry response, the plugin returns `statusCode: 401` and the gateway configuration captures that and returns the same status code.

## Resources

Useful resources that cover the topics of this article.

-   An article on [OAuth Introspection and Phantom Tokens](https://curity.io/resources/learn/introspect-with-phantom-token/)
-   [Tyk Self Managed Overview](https://tyk.io/self-managed/)
-   [Tyk Self Managed Quick Start Guide](https://tyk.io/docs/getting-started/quick-start/)
-   [gRPC](https://grpc.io/docs/what-is-grpc/introduction/)
