Common HTTP request headers¶
Billtrust APIs use custom headers for authentication, tracking, and testing. Which auth header you send depends on the lane (Platform vs External). See Connect before copying examples between products.
Lane summary¶
| Header | Platform (arc-aegis…) |
External (ext.arc-aegis…) |
|---|---|---|
X-Billtrust-Api-Key |
Platform user API key (documented default) | Also accepted if the value is an external key (btk_…) |
X-Billtrust-Auth |
Login access token | Not an external API key — do not send a JWT here expecting external API access |
X-API-Key |
Not the primary platform pattern | Documented default for Ingest, Remittance export, etc. |
X-BT-Corr-Id |
Optional | Optional |
X-API-Key¶
Used on External APIs (Ingest, Remittance export, and other services behind ext.arc-aegis…).
X-API-Key: btk_prod_…
- Credential: external API key issued via the platform Ext API Keys experience (not the classic Authentication API create-key curl).
- Validated by ext-api-proxy / external auth-service. Downstream product services often never see this header—they receive tenant identity from the gateway.
- Missing or invalid key → typically 401 from the gateway.
Details: Connect — External lane.
X-Billtrust-Api-Key¶
Platform lane: provides the API key that proves the caller is a valid platform API user. Generate it with the Authentication API. If the key is invalid, or the user permissions on the key do not allow the API, expect 401/403.
One of X-Billtrust-Api-Key or X-Billtrust-Auth is required for most Platform APIs outside of login.
External lane: the external gateway also accepts this header name as an alternate to X-API-Key, but the secret must still be an external (btk_…) key. Prefer X-API-Key in external API examples to match OpenAPI and product docs.
X-Billtrust-Auth¶
Platform access token from login. Used for interactive/session-style calls and for creating a platform API key. Tokens expire and must be refreshed.
One of X-Billtrust-Api-Key or X-Billtrust-Auth is required for most Platform APIs outside of authentication.
Do not use this header as a substitute for an external X-API-Key on ext.arc-aegis….
X-BT-Corr-Id¶
Optional correlation ID for the API call. Used to track the lifespan of a request. Generally reserved for internal use. If omitted, the platform may generate one.