Skip to main content
Borga authenticates every API request using API keys. You include your secret key in the Authorization header of each request. Requests without a valid key are rejected before they reach any endpoint. There are two key types — one for server-side calls and one for browser-side flows — and you should never mix them up.
Never commit a secret key to source control, expose it in client-side JavaScript, or share it in a public channel. If a secret key is compromised, rotate it immediately from the dashboard under Settings → API Keys.

​
Key types

Borga issues two distinct key types, each with a different scope and environment variant. Secret keys have full API access and must only ever appear in server-side code — environment variables, secrets managers, or backend configuration files. Publishable keys have a restricted scope limited to initiating embedded checkout sessions, making them safe to include in browser-side JavaScript.

​
Passing your secret key

Include your secret key as a Bearer token in the Authorization header of every request:
curl
There is no separate login step or token exchange — the key itself is the credential.

​
Merchant ID header

Most Borga endpoints require an X-Merchant-Id header identifying which merchant account the request is for. Your Merchant ID has the format mer_… and is visible in the dashboard under Settings → API Keys. You can also retrieve it programmatically:
curl
The GET /v1/merchants/current endpoint does not require the X-Merchant-Id header — it infers the merchant from the API key itself. Use it to look up your Merchant ID during initial setup.
Set the Merchant ID as an environment variable alongside your secret key so both are available to your server at runtime:

​
Idempotency

Network failures can leave you uncertain whether a request was processed. To safely retry a POST request without risking duplicate charges, include an Idempotency-Key header with a unique string (a UUID works well). Borga stores the result of the first request and returns the same response for any subsequent requests with the same key, without executing the operation again.
curl
Generate a fresh UUID for each distinct operation. Reusing the same key for a different payload will return the original response, not a new one — Borga deduplicates on the key alone, not the combination of key and body.

​
Test vs. live mode

The key prefix determines the mode of every request:
  • sk_test_… — test mode. No real charges are made. Card numbers, payments, and invoices are all simulated. Use this during development and staging.
  • sk_live_… — live mode. Requests process real ISK charges immediately.
You switch modes simply by swapping the key. No other configuration changes are required.

​
Authentication errors

A 401 response body looks like this:
Inspect the error.message field for a human-readable explanation before contacting support.