Authentication

Send your account’s secret key as a bearer token in the Authorization header of every request:

An authenticated request

curl https://api.63-180-91-99.sslip.io/payments/pay_in_01J9… \
  -H "Authorization: Bearer sk_live_in_…"

The key decides everything about the request: the merchant account it acts on, its market and its mode. A test key reads and writes only test data, a live key only live data. There is no other way to choose the account: a request carries no account or merchant id of its own.

When the key is refused

A request without a key, or with a key that is wrong, gets 401 Unauthorized and nothing runs. A test key works only in test mode, never with live payments; a test key of a market with no test environment gets 404 resource_missing.

Response · 401 Unauthorized

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="psp"

{"error": {"type": "invalid_request_error", "message": "Invalid API key provided."}}

The response says nothing about the key you sent, so check which one your server read: a test key where you meant live, a key of another account, a stale value in your environment.

A key that worked and has ended, revoked or replaced by a rotation whose expiry has passed, gets 401 with the code api_key_expired and the key’s prefix, from any address, so you can tell which key your server still sends:

Response · 401 Unauthorized, an ended key

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="psp"

{"error": {"type": "invalid_request_error", "code": "api_key_expired", "message": "Expired API key provided: sk_live_in_4fQx9aZ2…"}}

Put the account’s current key in its place: the merchant portal lists them under Settings › Developers › API keys.

A right key used from an address that its account’s IP allowlist does not list gets 403 with the code ip_not_allowed. The key is checked first, so a wrong key gets 401 from any address.

A right key can also be refused with 403 for the state of what it belongs to, and nothing runs. This comes after the IP allowlist, so a call from an address the allowlist does not list gets ip_not_allowed whatever the state:

• account_inactive: its account, or your merchant, is suspended. It works again once they are active. A key of a closed account is refused as a wrong key, with 401.
• market_not_enabled: your merchant is not enabled on the account’s market for the key’s mode: a live key needs the market active, a test key in test or active.

Your account manager can tell you why.

CLI keys

Coming soon

The novaro CLI and the merchant portal’s page that allows it are on their way: this section describes how their keys work then.

novaro login makes a CLI key, rk_test_<market>_…, once someone of your account allows it in the merchant portal. It works in test mode only, ends 90 days after it was made, and is never rotated: run novaro login again for another. It may make only the calls the CLI makes: read events, and create, read and confirm payments. Any other call gets 403 api_key_permission and nothing runs: use a secret key for it. An account has at most 10 working CLI keys, apart from its 10 secret keys of each mode.

Keys in the browser

Do not call the API from a browser or a mobile app: the key would be in the hands of everyone who uses it. Call it from your server, and give your front end only what it needs. The one exception is Try it in this API reference, which sends a test key you paste, and only to test mode (Test mode).