Authentication
Every request to the Merchant API must be authenticated with an API key and signed with a signing secret (covered in Signing). This page covers the API key.
API keys
Authenticate by sending your secret API key as a Bearer token:
Authorization: Bearer sk_test_8f4c2a9b7e1d6035a1c8e2f4b9d70a6c...
API keys identify your merchant account and the environment they belong to. There are two types:
| Type | Prefix | Where it is used |
|---|---|---|
| Secret key | sk_ | Server-side, for calling the Merchant API. Grants full API access — keep it confidential. |
| Publishable key | pk_ | Client-side contexts — it initializes Orchestr.js for card collection and selects the environment by its prefix. Non-confidential, and it cannot call the server-to-server Merchant API endpoints in this reference. |
Keys are also environment-scoped via their prefix, so you can tell at a glance which environment a key belongs to:
| Environment | Secret key prefix | Publishable key prefix |
|---|---|---|
| Sandbox | sk_test_ | pk_test_ |
| Live | sk_live_ | pk_live_ |
A secret key grants full access to your account in its environment. Never embed it in client-side code, mobile apps, or public repositories. If a key is exposed, rotate it immediately.
Getting and managing keys
API keys are created and managed from the Orchestr Dashboard, not through this API.
- The full key is shown only once, at creation time. Store it securely (for example in a secrets manager) — Orchestr stores only a salted hash and the last four characters, so it cannot show you the full value again.
- You can hold multiple active keys per account (up to 10 secret and 20 publishable keys), which is what makes zero-downtime rotation possible.
- Keys can be revoked at any time from the Dashboard; a revoked key stops working immediately.
Authentication errors
If the Authorization header is missing, malformed, or names a key that is unknown, revoked, or
expired, the API responds with HTTP 401 and an error envelope:
{
"code": "unauthenticated",
"message": "Missing or invalid authentication",
"request_id": "req_2c1f8a7b9e3d4051"
}
A request that authenticates successfully but fails signature verification returns a different code
(invalid_signature) — see Signing and Errors.
Next step
A valid API key is necessary but not sufficient: you must also sign the request.