Connect: gateways, keys, and headers¶
Billtrust public APIs run on two lanes. They look similar in docs and Swagger, but they use different base URLs, different credentials, and different ways to get a key. Mixing them is the most common integration failure.
Read this page once before calling any product API.
The two lanes¶
| Platform APIs | External APIs | |
|---|---|---|
| Who it's for | Platform automation against classic BTQ services | External integrators and product APIs fronted by the external gateway |
| Base URL (prod) | https://arc-aegis.billtrust.com |
https://ext.arc-aegis.billtrust.com |
| Path shape | /{service}/v{n}/… (often includes /tenants/{tenantId}/…) |
/api/v1/{service}/… |
| Auth header | X-Billtrust-Api-Key or X-Billtrust-Auth |
X-API-Key (preferred). The external gateway also accepts X-Billtrust-Api-Key when it carries an external key |
| Credential type | Platform user API key or login access token | External API key (btk_{env}_…) with scopes (service:action) |
| How you get a key | Self-serve via API — login, then create a key on the Authentication API | Platform Ext API Keys UI (admin / feature-gated). Keys are issued by the external auth service — not by the product APIs and not by the classic Authentication API flow below |
| Who validates | Aegis / internal platform stack | ext-api-proxy → external auth-service; product services often only see tenant identity |
| Products in these docs | Authentication, Users, Disputes, Payment rules, Credit, … | Ingest, Remittance export, (and related external APIs such as PDF ingestion) |
Non-production hosts follow the same pattern with an environment segment (for example arc-aegis-stage.billtrust.com and ext.arc-aegis-stage.billtrust.com). Deployed docs rewrite prod URLs by environment at runtime.
Pick your lane by product¶
| Product | Lane | Base URL (prod) | Auth |
|---|---|---|---|
| Authentication | Platform | https://arc-aegis.billtrust.com/authentication |
Login issues X-Billtrust-Auth; used to mint platform keys |
| Users | Platform | https://arc-aegis.billtrust.com/user |
X-Billtrust-Api-Key or X-Billtrust-Auth |
| Disputes | Platform | https://arc-aegis.billtrust.com/dispute |
X-Billtrust-Api-Key or X-Billtrust-Auth |
| Payment rules | Platform | https://arc-aegis.billtrust.com/payment-acceptance-rules |
X-Billtrust-Api-Key or X-Billtrust-Auth |
| Credit | Platform | https://arc-aegis.billtrust.com/creditappcore |
X-Billtrust-Api-Key or X-Billtrust-Auth |
| Ingest | External | https://ext.arc-aegis.billtrust.com/api/v1/ingest |
External key via X-API-Key |
| Remittance export | External | https://ext.arc-aegis.billtrust.com/api/v1/remittance-export |
External key via X-API-Key |
Keys: do not assume one key works on both lanes¶
Important
Platform keys and external keys are different credential systems.
- A key created with the Authentication API (platform self-serve) is for Platform APIs on
arc-aegis…. - An external key (
btk_…) created in the Billtrust platform Ext API Keys experience is for External APIs onext.arc-aegis…. - Do not assume a platform-generated key will authorize Ingest or Remittance export, or that an external
btk_key will authorize Disputes or Users.
Platform lane — self-serve API key¶
- Create a dedicated API user with the roles required for the APIs you call.
- Log in to obtain
X-Billtrust-Auth. - Create an API key via the Authentication API.
- Call Platform APIs with
X-Billtrust-Api-Key.
Details: Authentication.
External lane — platform-provisioned API key¶
- An administrator with access to the Ext API / System Administration experience in the Billtrust platform creates a key for your tenant.
- Choose scopes for the services you need (for example ingest read/write, remittance-export read/write).
- Store the plaintext key when it is shown (once). Format resembles
btk_prod_…/btk_stage_…. - Call External APIs on
ext.arc-aegis…with:
X-API-Key: btk_…your-external-key…
There is no public “create external key” endpoint on Ingest or Remittance export. Those services authenticate at the gateway; Remittance export never sees the raw key—it receives tenant identity from the proxy.
Headers cheat sheet¶
| Header | Lane | Purpose |
|---|---|---|
X-Billtrust-Api-Key |
Platform (required pattern in most platform examples) | Platform user API key |
X-Billtrust-Auth |
Platform | Short-lived access token from login |
X-API-Key |
External (documented pattern) | External API key (btk_…) |
X-Billtrust-Api-Key |
External (also accepted by the gateway) | Same external secret if you prefer this header name — still a btk_ external key, not a substitute for understanding which store issued it |
X-BT-Corr-Id |
Either | Optional correlation id |
Full descriptions: Common headers.
Common mistakes¶
| Mistake | What happens |
|---|---|
Call Ingest/Remittance on arc-aegis… without the external host/path |
Wrong gateway / 404 |
Send X-Billtrust-Auth (JWT) as if it were an external API key |
External gateway returns missing/invalid API key |
Reuse a platform Authentication API key on ext.arc-aegis… |
401 unless that value is actually an external btk_ key |
| Expect Remittance/Ingest to expose “create API key” | No such route — keys are gateway/platform-admin lifecycle |
| Assume one base URL for every product on the home page | Only true within a single lane |
Next steps¶
- Identify your product in the table above → note lane, base URL, header.
- Obtain the correct key for that lane.
- Follow the product overview for resources and payloads.
- Optional: open the interactive API reference for OpenAPI try-it (external API specs use the external base path).