Authentication

All API requests require authentication via an API Key using the standard Bearer token scheme. This page explains how to get your key and use it in your requests.

Get your API Key

1. Log in to your BeeL. account at app.beel.es
2. Go to Settings > API Keys
3. Click Create API Key
4. Select the environment (sandbox or production)
5. Give it a descriptive name (e.g., "My App" or "ERP Integration")
6. Copy the key immediately — it's only shown once

API Key Format

Sandbox key example:

beel_sk_test_a1b2c3d4e5f6g7h8

Production key example:

beel_sk_live_x9y8z7w6v5u4t3s2

Key properties:

• Each key is tied to a specific environment (sandbox or production)
• The base URL is the same (https://app.beel.es/api/v1) — the key determines the environment
• Keys never expire but can be manually revoked from the dashboard

Making Authenticated Requests

Include your API Key in the Authorization header using the Bearer scheme:

curl https://app.beel.es/api/v1/invoices \
  -H "Authorization: Bearer beel_sk_xxx"

Example: List invoices

curl https://app.beel.es/api/v1/invoices \
  -H "Authorization: Bearer beel_sk_test_a1b2c3d4e5f6g7h8"

Example: Create an invoice

curl -X POST https://app.beel.es/api/v1/invoices \
  -H "Authorization: Bearer beel_sk_test_a1b2c3d4e5f6g7h8" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "STANDARD",
    "issue_date": "2025-01-15",
    "recipient": {
      "recipient_type": "EXISTING",
      "customer_id": "550e8400-e29b-41d4-a716-446655440000"
    },
    "lines": [
      {
        "description": "Consulting",
        "quantity": 1,
        "unit_price": 100.00
      }
    ]
  }'

Using Environment Variables

Never include your API Key directly in your code. Use environment variables instead:

# Set the environment variable
export BEEL_API_KEY="beel_sk_test_a1b2c3d4e5f6g7h8"

# Use it in your requests
curl https://app.beel.es/api/v1/invoices \
  -H "Authorization: Bearer $BEEL_API_KEY"

Node.js

const apiKey = process.env.BEEL_API_KEY;

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

Python

import os
import requests

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

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

PHP

$apiKey = getenv('BEEL_API_KEY');

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

Using Official SDKs (Coming Soon)

The easiest way to authenticate will be using our official SDKs, currently under development:

Node.js SDK

import { BeeL } from '@beel_es/sdk';

const client = new BeeL({
  apiKey: process.env.BEEL_API_KEY,
});

// SDK handles Bearer authentication automatically
const invoices = await client.invoices.list();

Java SDK

import es.beel.sdk.BeeL;

BeeL client = new BeeL(System.getenv("BEEL_API_KEY"));

// SDK handles Bearer authentication automatically
var invoices = client.invoices().list();

See the SDKs documentation for more details.

Authentication Errors

If authentication fails, you'll receive a 401 Unauthorized response:

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}

Common causes:

• Missing Authorization header
• Incorrect format (must be Bearer {key}, not just the key)
• Incorrect API Key or typo
• API Key was deleted or regenerated
• Using a sandbox key to access production data (or vice versa)

Environments

BeeL. provides two separate environments:

Both environments:

• Share the same API base URL: https://app.beel.es/api/v1
• Have separate data (customers, invoices, etc.)
• Use the same API endpoints and features

Sandbox environment:

• ✅ Test freely without affecting real invoices
• ✅ Invoices don't count towards your monthly limit
• ✅ No VeriFactu submissions sent to AEAT
• ✅ Perfect for CI/CD pipelines and development

Production environment:

• ⚠️ Real invoices sent to AEAT via VeriFactu
• ⚠️ Invoices count towards your monthly limit
• ⚠️ Invoice numbers are legally binding

Security Best Practices

Do's ✅

• Use environment variables to store keys (never hardcode)
• Create separate keys for different apps or environments
• Delete unused keys immediately from the dashboard
• Rotate keys regularly (e.g., every 90 days)
• Use sandbox keys for all development and testing
• Store keys in secret managers (AWS Secrets Manager, HashiCorp Vault, etc.)

Don'ts ❌

• Never commit keys to Git repositories
• Never share keys via email, Slack, or public channels
• Never log keys in application logs
• Never use production keys in development
• Never include keys in client-side code (frontend apps)

If a key is compromised:

1. Immediately revoke the key from the dashboard
2. Create a new key with a different name
3. Update your applications with the new key
4. Review recent API activity for suspicious behavior

Next Steps

Now that you can authenticate your requests:

1. Explore the SDKs — Use our official libraries (Node.js, Java)
2. Learn about idempotency — Implement safe retries
3. Browse the API reference — See all available endpoints
4. Set up webhooks — Get real-time notifications

Questions? Email us at it@beel.es.