Authentication#
The Yusr API authenticates every request with a secret key sent as a bearer token. The key also decides the mode: a test key works with sandbox data, a live key moves real money.
Requests without a valid key fail with 401 authentication_failed. All requests must use HTTPS.
Make an authenticated request#
Test and live modes#
Your account has two separate environments that share one API host. The key you send picks the environment.
| Test mode | Live mode | |
|---|---|---|
| Secret key | sk_test_… | sk_live_… |
| Public key | pk_test_… | pk_live_… |
| Available | Immediately after sign-up | After your business verification is approved |
| Money | Simulated, nothing moves | Real bank transfers and settlements |
| Payments | Sandbox simulator | Customers' bank apps |
| Data | Test transactions, webhooks and events | Live transactions, webhooks and events |
Data never crosses modes. A test transaction is invisible to a live key (you get 404 not_found), and webhook
endpoints are registered per mode. Every object carries a mode field so you can always tell them apart.
Key types#
| Key | Prefix | Where it lives | What it can do |
|---|---|---|---|
| Secret key | sk_test_, sk_live_ | Your server only | Every API call, and server-side realtime subscriptions |
| Public key | pk_test_, pk_live_ | Can be shown in the dashboard and in client code | Identifies your account; it cannot read or create transactions |
| Client token | ct_ | A browser or mobile app | Subscribe to realtime updates for one transaction for 30 minutes |
| Webhook signing secret | whsec_ | Your server only | Verify that webhooks come from Yusr |
A secret key is shown in full once, when it is created or rolled. Yusr stores only a hash of it, so nobody, including our support team, can show it to you again. If you lose it, roll a new one.
Keep secret keys secret#
- Load keys from environment variables or a secrets manager, never from source code.
- Give each environment (development, staging, production) its own key.
- Browsers and apps that need live payment status should use a client token, which is scoped to a single transaction and expires after 30 minutes.
- If a key leaks, roll it immediately with no overlap (see below), then review recent activity in Developers → Logs.
Roll keys without downtime#
Rolling a secret key issues a new one and schedules the old one to stop working. Roll keys regularly, when a team member with access leaves, and immediately if a key may have leaked.
Roll the key#
In the dashboard, open Developers → API keys and choose Roll key. Pick an overlap of 0 to 24 hours: during the overlap, both the old and the new key work.
Deploy the new key#
Copy the new key (it is shown once) and roll it out to every server that calls the API.
Let the old key expire#
When the overlap ends, the old key is rejected with 401 authentication_failed. Check
Developers → Logs for requests still using the old key prefix before the window closes.
An overlap of 0 revokes the old key at once. Use it when a key has been exposed. Webhook signing secrets roll
separately, per endpoint: see Webhooks.
Restrict live keys by IP address#
You can lock a live secret key to the IP addresses of your servers. In Developers → API keys, edit the live
secret key and add one or more addresses. Requests from any other address fail with 403 ip_not_allowed, even
with a valid key.
An empty allowlist accepts requests from anywhere. Test keys are not restricted, so local development keeps working.
Authentication errors#
| Status | Code | Meaning | Fix |
|---|---|---|---|
| 401 | authentication_failed | The key is missing, malformed, revoked or expired. | Send Authorization: Bearer sk_… with a current key. |
| 403 | merchant_not_live | A live key was used before verification was approved, or live mode is paused. | Complete business verification in the dashboard. |
| 403 | ip_not_allowed | The live key has an IP allowlist that doesn't include the caller. | Add the server's egress IP or clear the allowlist. |
| 403 | merchant_suspended | The account is suspended. | Contact support. |
| 403 | sandbox_only | A live key called a sandbox-only endpoint such as the simulator. | Use a sk_test_ key. |
Every error uses the same shape:
The full list is in Errors.
Request IDs#
Every response carries an X-Request-Id header, and every error body repeats it as error.request_id. Log it
with your own request logs. When you contact support about a specific call, include the request ID: it lets us
find the exact request in seconds.
The libraries expose it as err.requestId (Node.js) and $e->getRequestId() (PHP).