# API keys

Authenticate with API keys for server-to-server integrations.

API Keys are the simplest way to authenticate. Create a key in the BeeL. dashboard and include it as a Bearer token in your requests.

## Get your API key

1. Log in to your BeeL. account at [app.beel.es](https://app.beel.es/)
2. Go to [**Settings > API Keys**](https://app.beel.es/ajustes/api-keys)
3. Click **Create API Key**
4. Select the **environment** (sandbox or production)
5. Choose the **scopes** your key needs (see [Available Scopes](/auth/scopes))
6. Copy the key immediately — it's only shown once

## Key format

| Component | Description |
|-----------|-------------|
| **Prefix** | `beel_sk_test_` (sandbox) or `beel_sk_live_` (production) |
| **Identifier** | Unique alphanumeric string |

```text
beel_sk_test_a1b2c3d4e5f6g7h8   # Sandbox
beel_sk_live_x9y8z7w6v5u4t3s2   # Production
```

<Callout type="warn">
  Keys are only shown **once** when created. Store them securely immediately.
</Callout>

## Making requests

Include your API Key in the `Authorization` header:

```bash
curl https://app.beel.es/api/v1/companies/{company_id}/invoices \
  -H "Authorization: Bearer beel_sk_test_a1b2c3d4e5f6g7h8"
```

## Code examples

### Node.js

```js
const apiKey = process.env.BEEL_API_KEY;

const response = await fetch('https://app.beel.es/api/v1/companies/{company_id}/invoices', {
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  }
});
```

### Python

```python
import os
import requests

api_key = os.environ.get('BEEL_API_KEY')

response = requests.get(
    'https://app.beel.es/api/v1/companies/{company_id}/invoices',
    headers={'Authorization': f'Bearer {api_key}'}
)
```

### PHP

```php
$apiKey = getenv('BEEL_API_KEY');

$ch = curl_init('https://app.beel.es/api/v1/companies/{company_id}/invoices');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $apiKey,
    'Content-Type: application/json'
]);
$response = curl_exec($ch);
```

## Scopes

Each API Key is created with specific scopes that limit which endpoints it can access. If a key doesn't have the required scope for an endpoint, the API returns `403` with `error.code` [`INSUFFICIENT_SCOPE`](/errors/INSUFFICIENT_SCOPE).

See [Available Scopes](/auth/scopes) for the full list and which endpoints require which scopes.

## Rate limits

API Key requests are rate-limited per key — see [Rate limits](/guides/rate-limits) for the current windows and headers.

## Key management

- Keys **never expire** automatically but can be manually revoked
- **Rotate keys regularly** (e.g., every 90 days)
- Create **separate keys** for different apps or environments
- **Delete unused keys** immediately from the dashboard

## Related

<Related>

- [Scopes](/auth/scopes) — what each permission lets a key call
- [Rate limits](/guides/rate-limits) — how many requests a key can make
- [Handling errors](/guides/handling-errors) — what an authentication failure looks like

</Related>

---

Full OpenAPI spec: https://docs.beel.es/api/openapi