> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pagos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# September 2026 API Migration

> Everything changing on September 1, 2026, and the steps to migrate your integration

<Warning>
  **On September 1, 2026, legacy API keys stop authenticating requests and the legacy API domains are retired.** Any integration still using a legacy key or a legacy endpoint will begin to fail on that date.
</Warning>

Several changes to the Pagos APIs land on the same date. They're independent of one another—you can complete them in any order, and finishing one doesn't complete the others—but they all need to be done before **September 1, 2026**.

| Change                                                               | Who's affected                       | Action required                                                              |
| :------------------------------------------------------------------- | :----------------------------------- | :--------------------------------------------------------------------------- |
| [Unified API keys](#1-unified-api-keys) replace legacy product keys  | All API users                        | Create a unified key and switch to `Authorization: Bearer`                   |
| [New API domains](#2-new-api-domains)                                | BIN Data API users                   | Point requests at `bin.pagos.ai`                                             |
| [New static IP addresses](#3-new-static-ip-addresses)                | BIN Data API users who allowlist IPs | Allowlist the new addresses                                                  |
| [Batch download URLs](#4-batch-download-urls) move to the new domain | BIN Data Batch users                 | Follow the returned URL dynamically, and allowlist the new download hostname |

<Note>
  These changes are independent. Migrating to the new domain does **not** migrate your API key, and creating a unified API key does **not** move you to the new domain. Check each section below against your integration.
</Note>

## Migration Checklist

<Steps>
  <Step title="Create a unified API key">
    Create a key on the main **API Keys** tab in the Pagos Service Panel—not under a product-specific tab. [Details below](#1-unified-api-keys).
  </Step>

  <Step title="Switch to Bearer authentication">
    Send `Authorization: Bearer <api key>` and remove any `x-api-key` header.
  </Step>

  <Step title="Update your endpoint URLs">
    Replace `parrot.prod.pagosapi.com` with `bin.pagos.ai` (or `parrot.sandbox.pagosapi.com` with `bin.sandbox.pagos.ai`).
  </Step>

  <Step title="Allowlist the new IP addresses">
    Add `13.248.157.210` and `166.117.218.160` to any firewall rules.
  </Step>

  <Step title="Check how you handle batch download URLs">
    Use the `url` value returned in the batch response as-is, rather than rebuilding it from a hardcoded domain—and if you allowlist that download hostname anywhere, [add the new one](#your-network-controls) before September 1.
  </Step>

  <Step title="Revoke your legacy keys">
    Once production is stable on the unified key, revoke the old product-specific keys.
  </Step>
</Steps>

## 1. Unified API Keys

Pagos originally issued a separate API key for each product, each with its own authentication format. The **unified API key** replaces all of them: one key that works across the entire Pagos suite and authenticates with a standard `Authorization: Bearer` header.

### Am I using a legacy key?

You're using a legacy key if either of the following is true:

* Your integration sends the API key in an `x-api-key` header
* You created the key under a **product-specific tab** in the Pagos Service Panel

<Warning>
  **This is the most common source of confusion.** In the Service Panel under **settings** → **Developers**, the first tab is **API Keys**—this is the one that issues unified keys. The tabs beside it (**Data Ingestion & Observability API**, **BIN Data API**, and **Action API**) still issue **legacy** keys, which stop working on September 1, 2026.

  If you create a replacement key under one of those product tabs, you haven't migrated. Always use the main **API Keys** tab.
</Warning>

| Legacy tab                             | Products it covered                                                    |
| :------------------------------------- | :--------------------------------------------------------------------- |
| **BIN Data API**                       | BIN Data API, BIN Data Batch, BIN Continuity API                       |
| **Action API**                         | Real-Time Account Updater, Batch Account Updater, Network Tokenization |
| **Data Ingestion & Observability API** | Data Ingestion API, Enrichment API                                     |

<Note>
  The **Action API** tab only appears if your organization is entitled to Account Updater or Network Tokenization, so you may not see all three tabs.
</Note>

### Creating a unified key

<Steps>
  <Step>
    Click your **settings** icon in the top-right corner of your Pagos Service Panel.
  </Step>

  <Step>
    Under **Developers**, click **API Keys**.
  </Step>

  <Step>
    In the **API Keys** tab, click **Create API Key** to add a new key to your account.
  </Step>

  <Step>
    In the side panel that opens, set your **Key Name**, then click **Create API Key**.
  </Step>

  <Step>
    Copy your new API Key and store it somewhere secure.

    <Warning>
      This is the only time you can view this key!
    </Warning>
  </Step>

  <Step>
    Click **I've Copied My Keys** to confirm and exit the side panel.
  </Step>
</Steps>

Unified API keys begin with the prefix `ak_`. A single key covers every Pagos product your organization is entitled to, so most integrations replace several product keys with one.

<Warning>
  Test Mode and Live Mode keys aren't interchangeable. Create one in each mode using the [environment toggle](/getting-started/managing-your-pagos-account#test-mode) in the top-right corner of the Service Panel. A Test Mode key won't authenticate production requests, and a Live Mode key won't work against the sandbox.
</Warning>

### Switching your authentication header

|                         | Legacy                     | Unified                           |
| :---------------------- | :------------------------- | :-------------------------------- |
| Header (BIN Data APIs)  | `x-api-key: <api key>`     | `Authorization: Bearer <api key>` |
| Header (all other APIs) | `Authorization: <api key>` | `Authorization: Bearer <api key>` |

<CodeGroup>
  ```bash Unified theme={null}
  curl --request GET \
    --url 'https://bin.pagos.ai/bins?bin=55630400' \
    --header 'Authorization: Bearer <api key>'
  ```

  ```bash Legacy theme={null}
  curl --request GET \
    --url 'https://bin.pagos.ai/bins?bin=55630400' \
    --header 'x-api-key: <api key>'
  ```
</CodeGroup>

<Warning>
  **Send only one authentication header.** If a request contains both `x-api-key` and `Authorization`, Pagos validates the `x-api-key` header and ignores the other—so a unified key sent alongside a leftover `x-api-key` header is treated as a legacy key and rejected. Remove the `x-api-key` header entirely.
</Warning>

## 2. New API Domains

The BIN Data APIs have moved to new domains:

| Environment | Legacy domain                 | New domain             |
| :---------- | :---------------------------- | :--------------------- |
| Production  | `parrot.prod.pagosapi.com`    | `bin.pagos.ai`         |
| Sandbox     | `parrot.sandbox.pagosapi.com` | `bin.sandbox.pagos.ai` |

Both the legacy and new domains work today. **The legacy domains are retired on September 1, 2026.**

<Note>
  Your API key type and your endpoint are independent. A legacy key authenticates against *both* domains today, and a unified key works against both as well. The fact that your current key works on `bin.pagos.ai` doesn't mean it will survive September 1—if it's a legacy key, it still needs to be replaced. See [Unified API Keys](#1-unified-api-keys).
</Note>

## 3. New Static IP Addresses

The new domains resolve to new static IP addresses. If you allowlist Pagos traffic in a firewall, add these:

* `13.248.157.210`
* `166.117.218.160`

The legacy domains continue to resolve to their original addresses—`99.83.189.213` and `75.2.25.63`—until they're retired on September 1, 2026. Keep both sets allowlisted while you're mid-migration, and remove the legacy pair once you've fully cut over.

## 4. Batch Download URLs

Responses from the BIN Data Batch [`/batch/files`](/bin-data-APIs/endpoint/file-snapshot) endpoint contain a `url` field pointing at the file to download.

Today, that URL still references the legacy domain even when you call the new one:

```json theme={null}
{
  "url": "https://parrot.prod.pagosapi.com/batch/files/download?preSignedUrl=..."
}
```

**This is expected.** On September 1, 2026, these URLs switch to the new domain:

```json theme={null}
{
  "url": "https://bin.pagos.ai/batch/files/download?preSignedUrl=..."
}
```

This switch happens server-side, on our side, with no release required from you. But it is **not** a no-op for everyone—there are two separate things to check.

### Your code

Use the returned `url` exactly as given, rather than extracting the path and appending it to a hardcoded domain. Integrations that follow the returned URL pick up the new domain automatically.

### Your network controls

<Warning>
  **If you allowlist the download URLs you get back, downloads will start failing on September 1, 2026.**

  Following the URL dynamically isn't enough on its own—the hostname inside it changes on that date. Any egress firewall rule, outbound proxy allowlist, or URL filter that permits `parrot.prod.pagosapi.com` for downloads must also permit `bin.pagos.ai` before September 1.
</Warning>

This is easy to miss, because nothing in your own code changes and the failure appears without a deploy. Check for the download hostname in:

* Outbound proxy or egress firewall rules
* URL or domain allowlists on a corporate network
* Any allowlist maintained by a data platform or ETL tool that fetches the file on your behalf

Add `bin.pagos.ai` (or `bin.sandbox.pagos.ai`) alongside your existing entry now, and remove the legacy hostname after the cutover. If you allowlist by IP rather than hostname, add the [new IP addresses](#3-new-static-ip-addresses).

<Warning>
  Pass the `preSignedUrl` value through unchanged. It contains a temporary, expiring token, and its internal structure may change over time—don't decode, parse, or build logic around its contents.
</Warning>

## What Doesn't Change

* **Request and response formats.** Apart from the batch `url` domain described above, no field is added, removed, or reformatted by this migration. Switching to a unified key has no effect on response bodies.
* **Other headers.** Account Updater and Network Tokenization still require `X-Merchant-ID`, unchanged.
* **Paths and query parameters.** Only the domain changes; `/bins`, `/batch/files`, and every other path stays the same.
* **Rate limits and entitlements.** Your unified key inherits the product access your organization already has.

## Troubleshooting

<AccordionGroup>
  <Accordion title="401: This API key is invalid.">
    Usually a key sent in the wrong header. Pagos chooses how to validate your key based on the header you use, and doesn't fall back to the other:

    * `x-api-key` is always validated as a **legacy** key
    * `Authorization: Bearer` is always validated as a **unified** key

    A unified key sent as `x-api-key`, or a legacy key sent as `Authorization: Bearer`, fails even though the key itself is valid. Confirm the key type and header match.

    Also check the key matches the environment you're calling—Test Mode keys don't authenticate production requests.
  </Accordion>

  <Accordion title="401: API requires an API key in 'x-api-key' header.">
    Your request reached a BIN Data API endpoint with no recognized authentication header. Confirm you're sending `Authorization: Bearer <api key>` and that the header isn't being stripped by a proxy or gateway in front of your integration.
  </Accordion>

  <Accordion title="I created a new key but it still doesn't work.">
    Check which tab you created it under. Keys created on the **BIN Data API**, **Action API**, or **Data Ingestion & Observability API** tabs are legacy keys and won't authenticate with `Authorization: Bearer`. Create the key on the main **API Keys** tab instead.
  </Accordion>

  <Accordion title="My key works on one product but not another.">
    Legacy keys only ever authenticate the single product they were issued for, so an integration calling several Pagos APIs may be holding one legacy key per product. A unified key covers every product your organization is entitled to.

    If a unified key is rejected by one product specifically, your organization may not be entitled to it—contact your Pagos Account Manager.
  </Accordion>

  <Accordion title="Requests time out or are refused after switching domains.">
    Check your firewall rules. The new domains resolve to [different IP addresses](#3-new-static-ip-addresses) than the legacy ones.
  </Accordion>

  <Accordion title="Batch file downloads started failing and we didn't change anything.">
    Most likely a network allowlist. From September 1, 2026, the `url` returned by [`/batch/files`](/bin-data-APIs/endpoint/file-snapshot) points at `bin.pagos.ai` instead of `parrot.prod.pagosapi.com`. If an egress firewall, outbound proxy, or URL filter only permits the legacy hostname, the download is blocked even though your integration is behaving correctly and nothing was deployed.

    Add `bin.pagos.ai` to the allowlist—or the [new IP addresses](#3-new-static-ip-addresses) if you filter by IP. See [Your network controls](#your-network-controls).
  </Accordion>

  <Accordion title="I lost the key value after creating it.">
    Pagos displays a key's value only once, at creation. If you didn't store it, revoke that key and create a replacement on the main **API Keys** tab.
  </Accordion>
</AccordionGroup>

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="My existing key works on both the legacy and new domains. Do I still need a new key?">
    Yes, if it's a legacy key. Which domain you call and which key type you use are two separate things. A legacy key authenticates against the new domain today, but it stops working everywhere on September 1, 2026. Check whether your key is legacy using the [guidance above](#am-i-using-a-legacy-key).
  </Accordion>

  <Accordion title="What happens on September 1, 2026?">
    Legacy API keys stop authenticating requests, and the legacy domains stop serving traffic. Requests using either begin to fail. Batch download URLs also start returning the new domain from that date.
  </Accordion>

  <Accordion title="Do I need a separate key for each Pagos product?">
    No—that's the point of the change. One unified key authenticates every product your organization is entitled to. You do need separate keys for Test Mode and Live Mode.
  </Accordion>

  <Accordion title="Can I run legacy and unified keys side by side?">
    Yes, until September 1, 2026. Both authenticate during the transition, so you can migrate one service or environment at a time. Send only one authentication header per request.
  </Accordion>

  <Accordion title="Does migrating change my API responses?">
    Only the batch download `url` domain, and only on September 1, 2026. Switching your key or your endpoint has no effect on response bodies. If you're seeing another difference, it isn't caused by this migration—contact [support@pagos.ai](mailto:support@pagos.ai) and we'll look into it.
  </Accordion>

  <Accordion title="How many unified keys can I create?">
    As many as you need. Separate keys per environment, service, or team make it easier to rotate or revoke one without disrupting everything else.
  </Accordion>
</AccordionGroup>

Still have questions about migrating? Email [support@pagos.ai](mailto:support@pagos.ai) and we'll help you through it.