> ## 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

> How to migrate your Pagos integration in preparation for changes coming on September 1, 2026.

We're making several changes to the Pagos APIs on **September 1, 2026** that will require you to take action. Each change is independent of one another and you can address them in any order. **You must complete all required actions before September 1, 2026**.

<CardGroup cols={2}>
  <Card title="Unified API Keys" icon="code" href="#unified-api-keys">
    **All API users** must replace all legacy product keys with a new unified key and switch to `Authorization: Bearer`
  </Card>

  <Card title="New API domains" icon="code-compare" href="#new-api-domains">
    **BIN Data API users** must send all requests to `bin.pagos.ai`
  </Card>

  <Card title="New static IP addresses" icon="check" href="#new-static-ip-addresses">
    **BIN Data API users who allowlist IPs** must update their allowlist to the new addresses
  </Card>

  <Card title="Batch download URLs" icon="download" href="#batch-download-urls">
    **BIN Data Batch users** must move to the new domain and allowlist the new download hostname
  </Card>
</CardGroup>

<Note>
  **Important Notes:**

  * These changes are independent of one another and must be addressed independently
  * Migrating to the new domain **doesn't** migrate your API key, and creating a unified API key **doesn't** move you to the new domain
  * Check each section below against your integration
</Note>

## Migration Checklist

If you're impacted by all impending integration changes, complete this entire checklist before September 1, 2026:

<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](#unified-api-keys).
  </Step>

  <Step title="Switch to Bearer authentication">
    Remove any legacy headers (`x-api-key`, `x-client-key`, `x-date`) and [replace them](#switching-your-authentication-header) with `Authorization: Bearer <api key>`.
  </Step>

  <Step title="Update your endpoint URLs">
    [Replace](#new-api-domains) `parrot.prod.pagosapi.com` with `bin.pagos.ai` in production and `parrot.sandbox.pagosapi.com` with `bin.sandbox.pagos.ai` in sandbox.
  </Step>

  <Step title="Allowlist the new IP addresses">
    [Add](#new-static-ip-addresses) `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. 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>

## 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.

You must update your existing keys to the unified API key by September 1. If either of the following is true, you have legacy API keys that must be updated:

* Your integration sends the API key in an `x-api-key` header (BIN Data APIs)
* Your integration sends `x-client-key` and `x-date` headers with an HMAC signature (Account Updater and Network Tokenization)
* You created the key under a **product-specific tab** in the developer settings of your Pagos account

<Warning>
  **This is the most common source of confusion.**

  In the **settings** dropdown menu, click **API Keys** under **Developers**. The first tab on this page is **API Keys**; this is where you can generate unified API keys. The other tabs (**Data Ingestion & Observability API**, **BIN Data API**, and **Action API**) still issue **legacy** keys, which will stop working on September 1, 2026.

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

<Frame>
  <img src="https://mintcdn.com/pagossolutionsinc/W8qSTaxtnIdzmapg/images/unified_API_keys.png?fit=max&auto=format&n=W8qSTaxtnIdzmapg&q=85&s=1c0275ebed2541cd27f42bb4f7584a55" alt="API Keys Unified vs Legacy" width="2684" height="1340" data-path="images/unified_API_keys.png" />
</Frame>

| Legacy Tab | Products Covered |
| :- | :- |
| **BIN Data API** | [BIN Data API](/bin-data-APIs/bin-data-api-overview), [BIN Data Batch](/bin-data-APIs/batch-api-overview), [BIN Continuity API](/bin-data-APIs/bin-continuity-api-overview) |
| **Action API** | [Real-Time Account Updater](/account-updater/real-time-api-overview), [Batch Account Updater](/account-updater/batch-api-overview), [Network Tokenization](/network-tokenization/overview) |
| **Data Ingestion & Observability API** | [Data Ingestion API](/data-ingestion-api/data-ingestion-api-overview), [Enrichment API](/data-ingestion-api/enrichment-api-overview) |

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

### Creating a Unified Key

Follow the instructions in the [Pagos API Authentication](/authentication/authentication-overview#generate-an-api-key) guide to generate your new unified API key. All unified 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>
  API keys are different for Test and Live Mode. 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.
</Warning>

### Switching Your Authentication Header

| | Legacy | Unified |
| :- | :- | :- |
| **Header (BIN Data APIs)** | `x-api-key: <api key>` | `Authorization: Bearer <api key>` |
| **Header (Account Updater & Network Tokenization)** | `x-client-key` + `x-date` + HMAC signature | `Authorization: Bearer <api key>` |
| **Header (Data Ingestion & Observability)** | `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 with each request; if a request includes both `Authorization` and a legacy `x-api-key` header, Pagos will validate the `x-api-key` value and ignore the other.
</Warning>

### Account Updater and Network Tokenization

If your integration uses [Account Updater](/account-updater/pagos-account-updater-tools) or [Network Tokenization](/network-tokenization/overview), the legacy authentication involved generating an HMAC signature and sending it with `x-client-key` and `x-date` headers. With the unified key, replace all three headers with a single `Authorization: Bearer <api key>` header. You can remove the HMAC signature generation code entirely.

**[Real-Time Account Updater (RTAU)](/account-updater/real-time-api-overview):** When using a unified API key, message encryption is no longer required. You can remove the Request Key and Response Key encryption steps from your integration if you choose. This is optional; we'll still accept encrypted payloads.

**Batch Account Updater:** [PGP encryption](/account-updater/batch-api-overview#register-encryption-keys) of the batch request and response files is still required regardless of which key type you use. Only the authentication header changes.

## 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` |

While both legacy and new domains work today, **the legacy domains will be retired on September 1, 2026.**

<Note>
  Your API key type and endpoint are independent. While both legacy and unified API keys authenticate against *both* domains during this transition time, both the legacy API keys and legacy domains will be retired on September 1, 2026. See [Unified API Keys](#unified-api-keys) to update your API keys.
</Note>

## 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.

## 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 on our side (server side), with no release required from you. That being said, check your code to ensure you 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.

### Update Network Controls

If you allowlist the download URLs you get back from the BIN Data Batch API, **downloads will start failing on September 1, 2026**. Following the URL dynamically isn't enough on its own, as 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.

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` (production) and `bin.sandbox.pagos.ai` (sandbox) 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](#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
* **Batch AU file encryption** - Batch Account Updater still requires PGP encryption of request and response files
* **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 confirm the key matches the environment you're calling. [Test Mode](/getting-started/managing-your-pagos-account#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. See the image in the [Unified API Keys](#unified-api-keys) section above for further clarification.
  </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 have access 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](#new-static-ip-addresses) than the legacy ones.
  </Accordion>

  <Accordion title="Batch file downloads started failing and we didn't change anything.">
    This is most likely caused by 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.

    Follow the steps under [Update Network Controls](#update-network-controls) to add `bin.pagos.ai` to the allowlist.
  </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 [generate a replacement](/authentication/authentication-overview#generate-an-api-key).
  </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?">
    If it's a legacy key, yes. 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](#unified-api-keys).
  </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 forward.
  </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** still 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 (starting 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).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.