Authentication

How to authenticate with the Baiyar API: bearer API keys, environments, project and merchant keys, restrictions, expiry and best practices.

Send your secret API key as a bearer token on every request:

Authorization: Bearer bk_test_…

Create an API key

A key is made in the dashboard (API Keys), for the environment you are in, and the whole key is shown once. See Get your API keys for the steps.

Make a request

Keep the key in an environment variable and send it in the Authorization header. GET /v1/account is the simplest call: it needs no permission and tells you who the key is.

curl "https://api.baiyar.com/v1/account" \
  -H "Authorization: Bearer $BAIYAR_KEY"

const response = await fetch("https://api.baiyar.com/v1/account", {
  headers: { Authorization: `Bearer ${process.env.BAIYAR_KEY}` },
});
console.log(await response.json());

import os
import requests

response = requests.get(
    "https://api.baiyar.com/v1/account",
    headers={"Authorization": f"Bearer {os.environ['BAIYAR_KEY']}"},
)
print(response.json())

{
  "data": {
    "livemode": false,
    "merchant": { "id": "mer_01k7q3m8x2v5t9n4b6c1d0e7fa" },
    "project": { "id": "prj_01k7q3m8x2v5t9n4b6c1d0e7fa" },
    "key": {
      "id": "apk_01k7q3m8x2v5t9n4b6c1d0e7fa",
      "kind": "project",
      "scopes": ["payments:read", "payments:write"]
    }
  },
  "meta": { "request_id": "req_Hy3k9QzT2LmN8vXa" }
}

data.livemode: false confirms that this is a test key. data.key.kind is project or merchant, and data.key.scopes lists its permissions.

API key format

A key is bk_test_ (sandbox) or bk_live_ (live) followed by 43 characters. The prefix identifies the environment where the key works.

Key	Environment	Host
`bk_test_…`	Sandbox	`https://api.baiyar.com`
`bk_live_…`	Live	`https://api.baiyar.com`

Both environments share one host, https://api.baiyar.com: the prefix of the key decides which one a request reaches. Nothing you do with a test key moves real money. We store only a hash of a key, so we cannot show it to you again.

Never put a key in a URL. A request with api_key, token or similar in its query string is refused, because URLs end up in logs.

Project keys and merchant keys

	Project key	Merchant key
Works for	One project	Every project of the merchant
`project_id` in requests	Not needed	Names the project
Reads the account’s balance	No	Yes
Can have `payouts:write`	Yes	No

A project can have up to 10 active keys in each environment (a merchant key counts for the merchant).

Restrict a key to your servers

A key can be limited to the IP addresses or ranges (CIDR) your servers call from, up to 20 of them. A call from anywhere else is refused with ip_not_allowed even if the key is right.

Expiry and rotation

A key can be given an expiry date when it is made, and after that date it stops working. Rotating a key makes a new one with the same permissions and leaves the old one valid for 24 hours. See Rotate API keys.

Permissions and limits

What a key may do is set by its permissions, and how often it may call by the rate limit.

Best practices

Always

Keep keys on your server, in an environment variable or a secret store.
Give a key only the permissions it needs, and restrict it to the addresses of your servers.
Use a separate key for each server or service, so you can revoke one without touching the others.
Revoke a key at once if you think it leaked.

Never

Put a key in a mobile app, a web page, a repository or a URL.
Send a live key to a place that is not under your control.

Common errors

Situation	Answer
No key, malformed key, unknown, expired or revoked key	`401` `invalid_api_key`
A key without the permission	`403` `insufficient_scope`
An address that is not allowed	`403` `ip_not_allowed`
Too many requests	`429` `rate_limited`