Skip to content
YusrDocs

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.

HTTP
Authorization: Bearer sk_test_...

Requests without a valid key fail with 401 authentication_failed. All requests must use HTTPS.

Make an authenticated request#

curl https://api.yusr.ng/v1/balance \
  -H "Authorization: Bearer $YUSR_SECRET_KEY"
JSON
{
  "object": "balance",
  "mode": "test",
  "currency": "NGN",
  "pending": 4925000,
  "available": 0,
  "settled": 0
}

Test and live modes#

Your account has two separate environments that share one API host. The key you send picks the environment.

Test modeLive mode
Secret keysk_test_…sk_live_…
Public keypk_test_…pk_live_…
AvailableImmediately after sign-upAfter your business verification is approved
MoneySimulated, nothing movesReal bank transfers and settlements
PaymentsSandbox simulatorCustomers' bank apps
DataTest transactions, webhooks and eventsLive 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#

KeyPrefixWhere it livesWhat it can do
Secret keysk_test_, sk_live_Your server onlyEvery API call, and server-side realtime subscriptions
Public keypk_test_, pk_live_Can be shown in the dashboard and in client codeIdentifies your account; it cannot read or create transactions
Client tokenct_A browser or mobile appSubscribe to realtime updates for one transaction for 30 minutes
Webhook signing secretwhsec_Your server onlyVerify 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#

StatusCodeMeaningFix
401authentication_failedThe key is missing, malformed, revoked or expired.Send Authorization: Bearer sk_… with a current key.
403merchant_not_liveA live key was used before verification was approved, or live mode is paused.Complete business verification in the dashboard.
403ip_not_allowedThe live key has an IP allowlist that doesn't include the caller.Add the server's egress IP or clear the allowlist.
403merchant_suspendedThe account is suspended.Contact support.
403sandbox_onlyA live key called a sandbox-only endpoint such as the simulator.Use a sk_test_ key.

Every error uses the same shape:

JSON
{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid or missing API key.",
    "request_id": "req_01M47EGDZGFZ057ZJ3A7SERW66"
  }
}

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.

HTTP
HTTP/1.1 201 Created
X-Request-Id: req_01M47EG1VQ8N35Q5MWQ1EE4B6G
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
Content-Type: application/json; charset=utf-8

The libraries expose it as err.requestId (Node.js) and $e->getRequestId() (PHP).