Authentication
How to authenticate your requests to the BeeL. API
The BeeL. API supports two authentication methods. Both use the Authorization: Bearer header.
| Method | Best for | How it works |
|---|---|---|
| API Keys | Server-to-server integrations | Create a key in the dashboard, use it as Bearer token |
| OAuth2 | MCP clients, third-party apps | User authorizes your app, you receive a JWT token |
Both methods enforce scopes that control which endpoints your token can access. See Available Scopes for the full list.
Quick Start
API Key (simplest)
curl https://app.beel.es/api/v1/invoices \
-H "Authorization: Bearer beel_sk_live_your_key_here"OAuth2 Token
curl https://app.beel.es/api/v1/invoices \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiI..."Environments
BeeL. provides two separate environments. The base URL is the same — the key or token determines the environment.
| Environment | API Key Prefix | OAuth2 | Purpose |
|---|---|---|---|
| Sandbox | beel_sk_test_ | Include sandbox scope | Testing. No AEAT submissions. |
| Production | beel_sk_live_ | Default (no sandbox scope) | Real invoices via VeriFactu. |
Authentication Errors
| HTTP Status | Code | Meaning |
|---|---|---|
| 401 | UNAUTHORIZED | Token missing, expired, or invalid |
| 403 | FORBIDDEN | Token valid but missing required scope |
| 429 | TOO_MANY_REQUESTS | Rate limit exceeded |
Security Best Practices
Treat API keys and OAuth2 client secrets like passwords. Anyone with your credentials can access user data.
- Use environment variables — never hardcode credentials
- Use sandbox for development and testing
- Rotate keys regularly and revoke unused ones
- Never commit credentials to Git repositories
- Never include credentials in client-side code