Skip to main content
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.
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.
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.

​
Migration Checklist

1

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

Switch to Bearer authentication

Send Authorization: Bearer <api key> and remove any x-api-key header.
3

Update your endpoint URLs

Replace parrot.prod.pagosapi.com with bin.pagos.ai (or parrot.sandbox.pagosapi.com with bin.sandbox.pagos.ai).
4

Allowlist the new IP addresses

Add 13.248.157.210 and 166.117.218.160 to any firewall rules.
5

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 before September 1.
6

Revoke your legacy keys

Once production is stable on the unified key, revoke the old product-specific keys.

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

​
Creating a unified key

1
Click your settings icon in the top-right corner of your Pagos Service Panel.
2
Under Developers, click API Keys.
3
In the API Keys tab, click Create API Key to add a new key to your account.
4
In the side panel that opens, set your Key Name, then click Create API Key.
5
Copy your new API Key and store it somewhere secure.
This is the only time you can view this key!
6
Click I’ve Copied My Keys to confirm and exit the side panel.
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.
Test Mode and Live Mode keys aren’t interchangeable. Create one in each mode using the environment toggle 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.

​
Switching your authentication header

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.

​
2. New API Domains

The BIN Data APIs have moved to new domains: Both the legacy and new domains work today. The legacy domains are retired on September 1, 2026.
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.

​
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 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:
This is expected. On September 1, 2026, these URLs switch to the new domain:
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

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

​
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

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.
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.
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.
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.
Check your firewall rules. The new domains resolve to different IP addresses than the legacy ones.
Most likely a network allowlist. From September 1, 2026, the url returned by /batch/files 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 if you filter by IP. See Your network controls.
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.

​
Frequently Asked Questions

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.
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.
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.
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.
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 and we’ll look into it.
As many as you need. Separate keys per environment, service, or team make it easier to rotate or revoke one without disrupting everything else.
Still have questions about migrating? Email support@pagos.ai and we’ll help you through it.