# 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** (type: `domain`) — 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 result is forwarded to the client's configured proxy destination.

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

    E->>C: POST /checkout/pay (card data)
    C-->>FT: DNS resolves to Firstoken ALB
    FT->>FT: Match inbound route by domain + path
    FT->>FT: Tokenize card data in request body
    FT->>P: Forward tokenized request to proxy destination
    P-->>FT: Response
    FT-->>E: Response (via client domain)
```

***

### Key Concepts

#### Inbound Route (type: `domain`)

An inbound route of type `domain` listens for requests arriving at the registered custom domain. Each route maps a specific path pattern on the client's domain to a proxy destination.

Multiple inbound routes can be created under the same custom domain — one per endpoint that handles card data. Endpoints that do not process card data do not require an inbound route.

#### Proxy

A proxy defines the upstream URL where Firstoken sends the processed request after tokenization. The proxy destination must be a different endpoint from the inbound route path. Configuring the same endpoint for both inbound and proxy creates a routing loop.

#### Custom Domain

The custom domain is the client's own domain (e.g., `api.client.com`) registered in Firstoken's infrastructure. Firstoken provisions the SSL certificate and configures the reverse proxy. The client is responsible for creating the CNAME record pointing their domain to Firstoken's load balancer, using the value provided by the Firstoken team.

***

### Setup Process

#### Client Responsibilities

<table><thead><tr><th width="82.8984375">Step</th><th>Action</th></tr></thead><tbody><tr><td>1</td><td>Create a Proxy in the Firstoken Console (<code>Console > Proxy</code>)</td></tr><tr><td>2</td><td>Create an Inbound Route of type <code>domain</code> and associate it with the proxy (<code>Console > Inbound Routes</code>)</td></tr><tr><td>3</td><td>Copy the Inbound Route ID</td></tr><tr><td>4</td><td>Contact Firstoken with: custom domain name, Account ID, and Inbound Route ID</td></tr><tr><td>5</td><td>Once notified by Firstoken, create the CNAME record pointing the domain to the provided ALB DNS value</td></tr></tbody></table>

#### Firstoken Responsibilities

Upon receiving the client's information, the Firstoken team:

* Registers the custom domain in the platform
* Links it to the provided inbound route
* Provisions the SSL certificate on the load balancer
* Configures and redeploys the reverse proxy
* Notifies the client when setup is complete and provides the CNAME target value

***

### Configuring Multiple Endpoints

If the client's API has multiple endpoints that handle card data, a separate inbound route must be created for each one. Each inbound route maps one path and connects to a proxy that defines the corresponding upstream destination.

**Example:**

| Client endpoint (inbound)     | Proxy destination (upstream)                  |
| ----------------------------- | --------------------------------------------- |
| `api.client.com/checkout/pay` | `https://internal.client.com/tokenized/pay`   |
| `api.client.com/vault/store`  | `https://internal.client.com/tokenized/store` |

{% hint style="danger" %}
The inbound path and the proxy destination must always differ. Configuring the same host and path for both causes an infinite routing loop.
{% endhint %}

***

### Body Mapping

Each inbound route is configured with a body mapping that defines which fields in the request body contain card data. Firstoken uses this mapping to locate and tokenize the correct fields before forwarding the request.

The mapping must reflect the exact structure of the request body as sent by the client's end users. Provide the request body schema to the Firstoken team at setup time.

***

### DNS Configuration

After Firstoken completes the setup, create a CNAME record in your DNS provider:

| Record type | Name             | Value                 |
| ----------- | ---------------- | --------------------- |
| CNAME       | `api.client.com` | Provided by Firstoken |

DNS propagation may take up to 48 hours depending on the provider and TTL settings. Firstoken will confirm when routing is operational.

***

### Contact

To initiate a Reverse Proxy setup or request changes to an existing configuration, contact the Firstoken team and provide the following:

<table><thead><tr><th width="219.5546875">Field</th><th>Description</th></tr></thead><tbody><tr><td>Custom domain</td><td>Full domain name to be registered</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 created in the Console</td></tr><tr><td>Endpoint schema</td><td>Request body structure for each endpoint handling card data</td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://firstoken.gitbook.io/api-docs/guides/implementing-reverse-proxy.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.