# Overview

How to authenticate your requests to the BeeL. API.

Authenticate every request with an **API Key** in the `Authorization: Bearer`
header. Each key carries **scopes** that control which endpoints it can access —
see [Scopes](/auth/scopes) for the full list.

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

Create and manage keys in the dashboard (**Settings → API Keys**) — see
[API Keys](/auth/api-keys).

## Environments

The base URL is always the same — the **key prefix** selects the environment.

| Environment | API Key prefix | Purpose |
|-------------|----------------|---------|
| **Sandbox** | `beel_sk_test_` | Testing. Invoices go to AEAT's test environment, so nothing is registered for real — see [Testing VeriFactu in sandbox](/verifactu/testing-in-sandbox). |
| **Production** | `beel_sk_live_` | Real invoices via VeriFactu. |

<Callout type="warn">
  **In sandbox, email only goes to you.** A `beel_sk_test_` key can only send to the
  account holder's own address (`+tag` variants included); any other recipient is refused
  with `403` [`ENVIO_NO_PERMITIDO`](/errors/ENVIO_NO_PERMITIDO). Send quotas are lower too — see
  [Sending email](/guides/sending-email).
</Callout>

<Callout type="info">
  **Some account changes need the live key.** Members, grants, invitations and your
  management of other accounts are the same in both environments, so changing them with a
  `beel_sk_test_` key answers `403` [`LIVE_CREDENTIAL_REQUIRED`](/errors/LIVE_CREDENTIAL_REQUIRED); handing
  ownership over is dashboard-only. The full list is in
  [Test and live keys](/multi-nif#test-and-live-keys).
</Callout>

## Authentication errors

| Error | Meaning |
|-------|---------|
| `401` [`UNAUTHORIZED`](/errors/UNAUTHORIZED) | Key missing, expired, or invalid |
| `403` [`INSUFFICIENT_SCOPE`](/errors/INSUFFICIENT_SCOPE) | Key valid but missing a required scope — `error.details.missing_scopes` names them, comma-separated |
| `429` [`RATE_LIMIT_EXCEEDED`](/errors/RATE_LIMIT_EXCEEDED) | Rate limit exceeded — see [Rate limits](/guides/rate-limits) |

## Security best practices

<Callout type="warn">
  **Treat API keys like passwords.** Anyone with your key can access your data.
</Callout>

- **Use environment variables** — never hardcode keys
- **Use sandbox** for development and testing
- **Rotate keys regularly** and revoke unused ones
- **Never commit keys** to Git repositories
- **Never include keys** in client-side code

---

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