> For the complete documentation index, see [llms.txt](https://firstoken.gitbook.io/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://firstoken.gitbook.io/api-docs/guides/implementing-reverse-proxy.md).

# Implementing Reverse Proxy

The Reverse Proxy product enables clients with their own card data APIs to route sensitive payment data through Firstoken's infrastructure without changing their existing API surface. Card data is intercepted, tokenized, and returned transparently — clients' systems and their end users interact only with the client's own domain.

This product combines three Firstoken components:

* **Inbound Route** (Domain type) — receives inbound requests on the client's domain
* **Proxy** — defines the upstream destination where Firstoken forwards the processed request
* **Custom Domain configuration** — handled by Firstoken upon request

{% hint style="warning" %}
Setup requires contacting Firstoken. Custom domain registration and SSL certificate provisioning are performed by the Firstoken team. Clients cannot complete this setup independently through the Console.
{% endhint %}

***

### How It Works

The client points their domain to Firstoken's infrastructure via a CNAME record. Firstoken provisions an SSL certificate and registers the domain. From that point, requests to the client's API pass through Firstoken's reverse proxy: card data is tokenized in transit, and the tokenized request is forwarded to the client's configured proxy destination.

```mermaid
sequenceDiagram
    participant E as End User
    participant FT as Firstoken Reverse Proxy
    participant P as Client Proxy (Upstream)

    E->>FT: POST /checkout/pay (card data)<br/>via Client Domain (CNAME)
    
    alt Path is configured
        FT->>FT: Match inbound route by path
        FT->>FT: Tokenize card data in request body
        FT->>P: Forward tokenized request
    else Path is not configured
        FT->>P: Forward request as-is (no tokenization)
    end
    
    P-->>FT: Response
    FT-->>E: Response (via client domain)
```

{% hint style="info" %}
The proxy destination receives the request with card data already tokenized. The original card values are never forwarded downstream.
{% endhint %}

***

### Setup Process

#### Step 1 — Create a Proxy

In the Firstoken Console, create a Proxy that defines the upstream destination where Firstoken will forward the tokenized request.

See [Create a Proxy](/api-docs/how-to/create-a-proxy.md) for field descriptions and steps.

{% hint style="danger" %}
The proxy destination must be a different endpoint from the inbound route path. Configuring the same host and path for both creates an infinite routing loop.
{% endhint %}

***

#### Step 2 — Create a Domain Inbound Route

In the Firstoken Console, create an Inbound Route, assign the Proxy created in Step 1, and enable the **Custom Hostname** toggle to configure it as a Domain Inbound Route.

See [Create an Inbound Route](/api-docs/how-to/create-an-inbound-route.md) for field descriptions and steps.

{% hint style="info" %}
If your API has multiple endpoints that handle card data, add a separate path configuration for each one using **+ Add a configuration**. Endpoints that do not process card data do not require a path configuration.
{% endhint %}

***

#### Step 3 — Contact Firstoken

Send the following information to the Firstoken team:

| Field               | Description                                                        |
| ------------------- | ------------------------------------------------------------------ |
| Custom domain       | Full domain name to be registered (e.g. `api.client.com`)          |
| Account ID          | Your Firstoken Account ID                                          |
| Inbound Route ID    | UUID of the Domain Inbound Route created in Step 2                 |
| Request body schema | Field structure for each path configuration that handles card data |

Firstoken will generate the SSL certificate and share the CNAME records you need to configure in your DNS provider.

***

#### Step 4 — Configure your DNS

Once you receive the CNAME records from Firstoken, create both records in your DNS provider:

<table><thead><tr><th width="246.296875">Record</th><th>Description</th></tr></thead><tbody><tr><td><strong>Domain redirect</strong></td><td>Points your domain to the Firstoken Route URL provided.</td></tr><tr><td><strong>Certificate validation</strong></td><td>Host and value provided by Firstoken. Required to validate the SSL certificate.</td></tr></tbody></table>

{% hint style="danger" %}
Both CNAME records must be created within 48 hours of receiving them from Firstoken. After that period the SSL certificate provisioning expires and the process must be restarted.
{% endhint %}

Once both records are created, notify the Firstoken team. Firstoken will validate the DNS configuration and complete the setup to allow requests from your domain to reach the reverse proxy. DNS propagation may take up to 48 hours depending on your provider and TTL settings.

***

### Body Mapping and Field Filtering

#### Body Mapping

Each Inbound Route is configured with a field mapping that identifies which fields in the request body contain card data. This mapping is set in the Console when creating the Inbound Route.&#x20;

See [Create an Inbound Route](/api-docs/how-to/create-an-inbound-route.md) for the list of supported mapping fields (e.g. `cardnumber`).

#### Field-Level Filtering

{% hint style="warning" %}
Configuring a filter that routes requests based on the value of a specific field — for example, routing only requests where `type: Card` and skipping `type: PSE` — requires intervention by the Firstoken team and cannot be configured through the Console.

To request this configuration, contact Firstoken with:

* The Inbound Route ID (`Domain` type) already created
* The specific path (route) to be filtered
* The field name and the value to filter on

Any subsequent changes to field-level filtering on an existing route must also be requested through Firstoken support.
{% endhint %}

***

### Configuring Multiple Endpoints

If your API has multiple endpoints that handle card data, add a separate path configuration for each one within the same Domain Inbound Route using **+ Add a configuration**. Each path configuration defines its own field mapping independently, but all configurations share the same Proxy destination.

**Example:**

<table><thead><tr><th width="314.03125">Inbound path</th><th>Proxy destination</th></tr></thead><tbody><tr><td><code>/checkout/pay</code></td><td><code>https://internal.client.com/upstream</code></td></tr><tr><td><code>/vault/store</code></td><td><code>https://internal.client.com/upstream</code></td></tr></tbody></table>

{% hint style="danger" %}
The path defined in each configuration and the destination path in the associated Proxy must always differ. Configuring the same host and path for both causes an infinite routing loop.
{% endhint %}

***

### Validating the Integration

Once Firstoken confirms the setup is complete and DNS has propagated, validate the integration end to end:

1. Send a test request to your domain with card data in the body.
2. Confirm the request reaches your proxy destination.
3. Confirm the card fields in the forwarded request contain token values, not the original card data.
4. Confirm the response is returned correctly to the original caller.

If the request is not reaching the proxy destination or card data is not being tokenized, contact Firstoken support with the Inbound Route ID and a description of the observed behavior.

***

### Reference

#### Information Required by Firstoken

<table><thead><tr><th width="263.58984375">Field</th><th>Description</th></tr></thead><tbody><tr><td>Custom domain</td><td>Full domain name (e.g. <code>api.client.com</code>)</td></tr><tr><td>Account ID</td><td>Your Firstoken Account ID</td></tr><tr><td>Inbound Route ID</td><td>UUID of the inbound route</td></tr><tr><td>Request body schema</td><td>Field structure for each endpoint handling card data</td></tr><tr><td>Filter field (if applicable)</td><td>Field name, path, and value for field-level filtering</td></tr></tbody></table>

#### Related Pages

* [Create a Proxy](/api-docs/how-to/create-a-proxy.md)
* [Create an Inbound Route](#step-2-create-an-inbound-route)
* [Configure a Custom Domain](/api-docs/guides/configure-a-custom-domain.md)