Skip to main content

​
Two kinds of key

The split matters because they do different things. A secret key creates and manages payment sessions — it can move money on your behalf. A publishable key reads reference data, prices routes and reads balances. The customer-wallet Deposit creation path is available when you configure the key’s exact origin and Hypermid enables publishable Deposits for the partner; otherwise the server rejects the request with a setup error.
A secret key in a browser bundle is extractable by every visitor. The SDK enforces this rather than documenting it: payments.* throws before issuing a request if window exists.

​
The prefix picks the environment

A secret key’s prefix is not decoration — it is the environment switch:
  • sk_test_… → sandbox. Testnets only. No real money can move.
  • sk_live_… → production. Mainnets only.
Both go to the same hostname. There is no separate sandbox URL, and the confinement is enforced server-side on the key, so a misconfigured chain id is rejected rather than honoured. See Environments.

​
Why Bearer, not x-api-key

The backend reads the secret from Authorization only, deliberately. A header that leaks into a log line or a proxy trace must not be replayable as a secret, so the two channels are kept apart. Sending a secret as x-api-key fails auth rather than quietly working. Sending a publishable key where a secret is required returns a specific error rather than doing less:

​
Public routes

Some payer-facing reads take no key at all — GET /v1/payments/{id}/public, GET /v1/payments/quote, the pay and deposit calls, and the anonymous GET /v1/status. They are scoped to a single session id and return only what is safe to render to the person paying. This is why the Postman collection marks them noauth: attaching a bearer token to a route that never needed one is how a secret key ends up somewhere it should not be.

​
Keeping keys safe

If a secret key reaches a repo, a log aggregator or a support ticket, treat it as compromised and ask us to reissue it. Rotating an uncompromised key on a timer mostly creates outages.
A single key used by staging and production makes the audit trail useless and guarantees that revoking one breaks the other.
A webhook signing secret is not an API key. It only verifies that a delivery came from us — see Webhooks.