> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bitliva.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authenticate requests with your Bitliva API key

> Send your Bitliva API key as a bearer token on every request, understand sandbox and live modes, and handle 401 and 403 authentication errors.

The Bitliva Merchant API authenticates every request with your API key, sent as a bearer token in the `Authorization` header. There are no other credentials to manage for API calls.

## Send your API key

```bash theme={null}
curl https://merchant.bitliva.com/api/v1/me \
  -H "Authorization: Bearer $BITLIVA_API_KEY"
```

Keep the key on your server. Never ship it in a mobile app or browser code, because anyone who has it can act on your wallet and your customers.

## Create an API key

**1. Sign in to the merchant dashboard**

Go to [merchant.bitliva.com](https://merchant.bitliva.com) and sign in.

**2. Pick the mode**

Use the **Sandbox / Live** switch under **Environment** in the sidebar. Keys belong to one mode: a sandbox key only works in the sandbox, and a live key only works on live data. Live keys are available once your business is verified.

**3. Open API keys**

Open **API keys** from the menu, or go straight to [merchant.bitliva.com/api-keys](https://merchant.bitliva.com/api-keys).

**4. Name and create the key**

Enter a name that tells you where the key is used, such as `Production server`, then select **Create key**.

**5. Copy the key**

The new key is shown once, in a pop-up, with a **Copy** button. Store it in your server's secrets right away. Bitliva keeps only a hash of it, so it cannot be shown again. If you lose it, create a new one.

Sandbox keys start with `bl_test_` and live keys with `bl_live_`. You can have up to 10 active keys per mode.

## View your keys

The **API keys** page lists the active keys for the mode you are in. Each row shows the name, the start of the key (for example `bl_test_a1b2c3...`), when it was created and when it was last used. Keys never show in full after you create them.

## Rotate or revoke a key

To rotate a key without downtime:

1. Create a new key and deploy it to your server.
2. Check that requests work with the new key. The old key's **Last used** time stops changing once nothing uses it.
3. Select **Revoke** on the old key and confirm.

Revoking takes effect immediately: anything still using that key gets `401` with `invalid_api_key`. If a key leaks, revoke it straight away and create a new one.

## Sandbox and live modes

Responses such as `GET /me` and `GET /balance` include a `mode` field so you can tell which environment you are talking to. Sandbox responses report `test`, and live webhook payloads report `live`.

* The sandbox allows 5 customers. Beyond that you get `customer_limit_reached`.
* Sandbox-only endpoints, such as the deposit simulator, return `sandbox_only` when called outside the sandbox.
* Live access needs a verified business. Until then, live requests return `live_not_enabled`.

See [Sandbox testing](https://docs.bitliva.com/guides/sandbox.md) for the sandbox-only helper.

## Authentication errors

| HTTP status | `code` | What it means |
| - | - | - |
| 401 | `invalid_api_key` | The API key is missing, wrong or revoked. |
| 403 | `account_inactive` | Your merchant account is not active. Contact support. |
| 403 | `live_not_enabled` | Live access is not enabled: your business is not verified yet, or the account is suspended. |
| 403 | `sandbox_only` | This endpoint only exists in the sandbox. |

## Rate limits

If you send too many requests, the API responds with `429` and the code `rate_limited`. Wait the number of seconds given in the `Retry-After` header before you try again.

For the full list of codes, see [Errors and response format](https://docs.bitliva.com/errors.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.