Authentication
The X-API-KEY header, live vs test keys, and rotation.
The dashboard (merchant login, admin, support) authenticates with a JWT bearer token. Everything in this API reference — pay-in, pay-out, webhook configuration — authenticates with an API key instead. If you're integrating Orivanta Pay into your own backend, this page is the one that applies to you.
The header
Every request to /api/v1/pay-in/*, /api/v1/pay-out/* and /api/v1/webhook must carry:
X-API-KEY: sk_live_a1b2c3d4e5f6...There's no separate client ID, no OAuth handshake, no signing of the request itself (that's the webhook direction, not this one). The key is the whole credential — treat it exactly like a database password.
Key format
| Field | Type | Description |
|---|---|---|
prefix | string | "sk_live_" for a live key, "sk_test_" for a test key. |
body | string | 128 hex characters, cryptographically random. The full key is shown once, at creation or rotation, and never again. |
Test keys behave identically to live keys — same validation, same response shapes — but nothing they touch moves real money. Use them for everything until you're ready to go live.
One active key per application
An application can hold one active key at a time, live or test —
creating a second one returns 409 API_KEY_ALREADY_ACTIVE. If you need a
live and a test integration running concurrently, use two applications.
Rotating a key
Rotation issues a new key and immediately invalidates the old one — there's no overlap window, so deploy the new key before rotating if you can't afford a gap:
curl -X POST https://api.orivantapay.com/api/v1/merchants/apps/{appId}/api-keys/rotate \
-H "Authorization: Bearer <dashboard JWT>" \
-H "Content-Type: application/json" \
-d '{ "name": "production key", "environment": "LIVE" }'(This particular call is dashboard-authenticated — it's how you manage keys, as opposed to how you use one.)
What an invalid key looks like
A missing or unrecognized X-API-KEY doesn't return a dedicated "bad key" error — it falls through to a generic 401 Unauthorized, the same response you'd get from any unauthenticated request. If your integration is getting 401s, check the header name and prefix before anything else.