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

# Authentication

> Learn how to authenticate with the bitbybit Open API

## API Key Authentication

All API requests must include an API key in the `x-api-key` header.

```bash theme={null}
curl -X GET "https://api.bitbybit.studio/customer/open/v1/customers" \
  -H "x-api-key: bbb_live_abc123..."
```

### Creating an API Key

1. Log in to your bitbybit dashboard
2. Navigate to **Settings > Developer**
3. Click **Create API Key**
4. Give it a name and select the scopes (permissions) it needs
5. Click **Create** and copy the key immediately

<Warning>
  The raw API key is only shown once at creation time. Store it securely — you won't be able to retrieve it again.
</Warning>

### Key Format

| Environment | Prefix      | Example                    |
| ----------- | ----------- | -------------------------- |
| Production  | `bbb_live_` | `bbb_live_a1b2c3d4e5f6...` |
| Test        | `bbb_test_` | `bbb_test_a1b2c3d4e5f6...` |

### Scopes

API keys are scoped to specific resources and actions. Available scopes:

| Resource    | Actions             | Description                         |
| ----------- | ------------------- | ----------------------------------- |
| `customers` | READ, WRITE, DELETE | Manage customer records             |
| `orders`    | READ, WRITE         | Manage orders                       |
| `products`  | READ, WRITE, DELETE | Manage product catalog              |
| `messages`  | READ, WRITE         | Send and retrieve WhatsApp messages |

A key with `READ` access to `customers` can list and get customers, but cannot create or update them.

### Key Rotation

To rotate an API key without downtime:

1. Go to **Settings > Developer**
2. Click the menu on your active key and select **Rotate**
3. A new key is created and the old key gets a 24-hour grace period
4. Update your application with the new key
5. The old key automatically stops working after the grace period

### IP Whitelisting

You can restrict an API key to specific IP addresses or CIDR ranges. When configured, only requests from those IPs are accepted — all others receive a `403` error.

See [IP Whitelisting](/api-reference/ip-whitelisting) for setup instructions and supported formats.

### Error Responses

| Status | Code                 | Description                                                                |
| ------ | -------------------- | -------------------------------------------------------------------------- |
| 401    | `MISSING_API_KEY`    | No `x-api-key` header provided                                             |
| 401    | `INVALID_API_KEY`    | Key is invalid, revoked, or expired                                        |
| 403    | `INSUFFICIENT_SCOPE` | Key doesn't have the required scope                                        |
| 403    | `IP_NOT_ALLOWED`     | Request IP is not in the key's [allowlist](/api-reference/ip-whitelisting) |