> 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/configure-a-custom-domain.md).

# Configure a Custom Domain

Configure a client-owned domain for Firstoken Reverse Proxy.

A custom domain lets clients expose a Firstoken Reverse Proxy through their own domain. For example, `api.client.com`.

Firstoken configures the domain, route association, and SSL certificate. The client updates DNS after receiving the CNAME target.

{% hint style="warning" %}
Custom domains require Firstoken configuration. The Console cannot complete this setup independently.
{% endhint %}

### Before you start

Create an Inbound Route with type `domain` in the Console. Associate it with the Proxy that forwards requests to your upstream API.

The inbound route must use the custom domain and the path that receives card data.

### Send these details to Firstoken

| Field            | Description                                             |
| ---------------- | ------------------------------------------------------- |
| Custom domain    | Full domain name to register, such as `api.client.com`. |
| Account ID       | Your Firstoken Account ID.                              |
| Inbound Route ID | ID of the Inbound Route with type `domain`.             |

### Firstoken configuration

Firstoken completes the following configuration:

1. Registers the custom domain.
2. Associates the domain with the provided Inbound Route.
3. Provisions an SSL certificate.
4. Configures and deploys the reverse proxy.
5. Provides the CNAME target for your DNS record.

### Client responsibilities

The client completes these steps:

1. Creates the Proxy in the Firstoken Console.
2. Creates an Inbound Route of type `domain` and associates it with the Proxy.
3. Sends the required details to Firstoken.
4. Creates the CNAME record after Firstoken provides the target.

### Configure DNS

After Firstoken provides the target, create or update the CNAME record with your DNS provider.

| Record type | Name              | Value                              |
| ----------- | ----------------- | ---------------------------------- |
| CNAME       | `api.example.com` | CNAME target provided by Firstoken |

Use the exact CNAME target provided by Firstoken. DNS propagation time depends on your provider and TTL settings.

{% hint style="warning" %}
Configure the CNAME record within 48 hours of receiving the target. After 48 hours, Firstoken must generate the certificate configuration again.
{% endhint %}

### Activation

After DNS propagation, Firstoken verifies the domain response, certificate, and reverse proxy routing. Firstoken confirms when the custom domain is active.

{% hint style="info" %}
Do not direct the custom domain to the upstream API. Point it only to the CNAME target provided by Firstoken.
{% endhint %}

### Troubleshooting

If activation is delayed, verify the CNAME value and confirm that no conflicting DNS record exists for the same hostname. Contact Firstoken if the record resolves correctly but the endpoint remains unavailable.