Authentication
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 for the full list.
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.
Environments
The base URL is always the same — the key prefix selects the environment.
| Environment | API Key prefix | Purpose |
|---|---|---|
| Sandbox | beel_sk_test_ | Testing. No AEAT submissions. |
| Production | beel_sk_live_ | Real invoices via VeriFactu. |
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. Send quotas are lower too — see
Sending email.
Authentication errors
| HTTP Status | Code | Meaning |
|---|---|---|
| 401 | UNAUTHORIZED | Key missing, expired, or invalid |
| 403 | FORBIDDEN | Key valid but missing a required scope |
| 429 | RATE_LIMIT_EXCEEDED | Rate limit exceeded — see Rate limits |
Security best practices
Treat API keys like passwords. Anyone with your key can access your data.
- 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