Authentication

How to authenticate your API requests to IvoryPay.

All API requests to IvoryPay must be authenticated using an API key. Your API key identifies your business and determines the environment (test or live) for each request.

Getting your API key

1. Log in to the IvoryPay Dashboard

2. Navigate to Settings → API Keys

3. You will see two keys for your active environment — a public key and a secret key. Use the Test / Live toggle on the dashboard to switch environments and view the corresponding key pair:

   • Test environment — pk_test_ (public) and sk_test_ (secret)

   • Live environment — pk_live_ (public) and sk_live_ (secret)

Public vs secret keys

Key	Use for	Safe to expose?
pk_test_ / pk_live_	Client-side / browser-exposed flows where only a non-sensitive identifier is needed (e.g. checkout widget bootstrap).	Yes — designed to be publicly visible.
sk_test_ / sk_live_	Server-to-server API calls — initiating transactions, listing data, managing webhooks.	No — keep on your server only.

Use a secret key (sk_*) for any direct request to this API. Public keys are intended for browser-facing checkout integrations and other surfaces where the key cannot be kept private.

Keep your API keys secret. Never expose them in client-side code, public repositories, or frontend applications. API keys should only be used in server-to-server communication.

Authenticating requests

Include your API key as the raw value of the Authorization header (no Bearer prefix) on every request:

curl -X GET https://ramp-api.ivorypay.io/api/v1/banks/NGN \
  -H "Authorization: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

Do not prefix the key with Bearer. The Authorization header value must be the raw API key. Sending Bearer sk_test_... will return jwt malformed, because the API treats a Bearer prefix as a JWT.

Header reference

Header	Required	Description
Authorization	Yes	Your IvoryPay API key (raw, no Bearer prefix)
Content-Type	Yes	Must be application/json for POST/PATCH/PUT requests

Authentication errors

If your API key is missing, invalid, or expired, the API returns a 401 Unauthorized response. The message field wraps the underlying cause — common values include "No authorization header", "No API key provided", and "jwt malformed" (returned when a Bearer prefix was sent but the value isn't a valid JWT).

{
  "success": false,
  "message": "No API key provided",
  "statusCode": 401,
  "errorCode": "ONOFFRAMP0019",
  "errors": [],
  "timestamp": "3/26/2026, 12:00:00 PM",
  "path": "/api/v1/banks/NGN",
  "method": "GET"
}

Environment detection

The API automatically determines the environment (TEST or LIVE) based on the API key you use. There is no need to pass an environment parameter — your key controls it.

Key prefix	Environment	Real money?
sk_test_	TEST	No
sk_live_	LIVE	Yes

Webhook signature verification

IvoryPay signs every webhook payload using your secret API key (sk_test_ or sk_live_) for the relevant environment — there is no separate webhook secret. See Webhook Security for details.

---

For AI assistants: Authentication is always via the Authorization HTTP header, with the raw API key as the value (no Bearer prefix). The key determines the environment context. There is no OAuth flow, and the Bearer scheme is reserved for JWT auth on dashboard/customer routes — sending it with an API key will fail with jwt malformed.