API Keys

API keys allow you to access your BeePass data from external applications, scripts, or third-party integrations without using the web interface. Each key has granular permissions per resource.

How it works

[Your application]
    │ Authorization: Bearer bp_live_a3f8...5e82
    ▼
https://beepass.io/api/v1/queens
    │ SHA-256 validation → DB lookup → permission check
    ▼
[JSON data returned]

1. Create a key from the web interface (avatar menu → API Keys)
2. Copy the key — it will only be displayed once
3. Use it in the Authorization header of your requests

Key format

bp_live_ + 64 hexadecimal characters = 72 characters

Example: bp_live_a3f8e2b1c4d5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1

Security

The raw key is only shown once during creation. BeePass only stores a SHA-256 hash — it is impossible to recover a lost key. You will need to create a new one.

Usage

Add the key to the Authorization header of each request:

curl -H "Authorization: Bearer bp_live_a3f8..." \
     https://beepass.io/api/v1/queens

const response = await fetch('https://beepass.io/api/v1/queens', {
  headers: {
    'Authorization': 'Bearer bp_live_a3f8...',
    'Content-Type': 'application/json'
  }
});
const data = await response.json();

import requests

headers = {
    'Authorization': 'Bearer bp_live_a3f8...',
    'Content-Type': 'application/json'
}
response = requests.get('https://beepass.io/api/v1/queens', headers=headers)
data = response.json()

Permissions

Each key defines an access level per resource:

Resource	Description
Queens	F0 and F1 queens (breeding stock, production)
Evaluations	Performance evaluations
BLUP	Estimated Breeding Values (EBV)
Hive	Apiaries and hives
Account	Profile and account settings

Permission levels

Level	Read (GET)	Write (POST/PUT/DELETE)
None	-	-
Read	Yes	-
Write	Yes	Yes

tip

Write level automatically includes read access. No need to set both.

Preset templates

Template	Description	Permissions
Read-only	View all data	All resources in read mode
Evaluator	Field evaluation input	Evaluations in write, rest in read (except Hive)
Custom	Manual configuration	You choose each permission

Restrictions

Expiration (TTL)

Set a lifetime for your key:

Option	Description
7 days	Testing and development
30 days	Temporary integrations
90 days	Standard usage
365 days	Long-term integrations
Never	No automatic expiration

An expired key is automatically rejected. It remains visible in the list with "Expired" status.

IP restriction

Limit key usage to specific IP addresses for enhanced security:

• Single IP: 203.0.113.5
• CIDR subnet: 192.168.1.0/24

If no IP is set, the key can be used from any address.

info

The IP restriction is checked on every request. The client IP is extracted from CF-Connecting-IP, X-Forwarded-For or X-Real-IP headers.

Key management

Create a key

Access the API Keys page from the avatar menu in the header, then click Generate key. The 4-step wizard guides you:

1. Name — Choose a descriptive name and a permission template
2. Permissions — Adjust permissions per resource (custom mode)
3. Restrictions — Set expiration and allowed IPs
4. Generated key — Copy your key immediately

Disable / Re-enable

Use the toggle switch in the "Enable" column to temporarily disable a key without deleting it. A disabled key is immediately rejected by the API.

Revoke

Click the trash icon then confirm the revocation. The key changes to "Revoked" status and cannot be reactivated.

Limits

Limit	Value
Max keys per user	20
Creations per hour	10
Name length	1 to 100 characters

Management API

Keys are managed via the standard REST API (Supabase session authentication):

Method	Route	Description
GET	/api/api-keys	List your keys (without hash)
POST	/api/api-keys	Create a new key
PUT	/api/api-keys/{id}	Update name or status
DELETE	/api/api-keys	Revoke a key

Create a key (POST)

curl -X POST https://beepass.io/api/api-keys \
  -H "Content-Type: application/json" \
  -b "sb-cookie=..." \
  -d '{
    "name": "My mobile app",
    "permissions": {
      "queens": "read",
      "evaluations": "write",
      "blup": "read",
      "hive": "none",
      "account": "read"
    },
    "expires_in_days": 90,
    "ip_allowlist": ["203.0.113.0/24"]
  }'

Response (201):

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "key": "bp_live_a3f8e2b1c4d5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1",
    "key_prefix": "bp_live_a3f8e2b1...f0a1"
  }
}

Revoke a key (DELETE)

curl -X DELETE https://beepass.io/api/api-keys \
  -H "Content-Type: application/json" \
  -b "sb-cookie=..." \
  -d '{ "id": "550e8400-e29b-41d4-a716-446655440000" }'

Error codes

Code	Situation
400	Invalid parameters (name, permissions, TTL, IP)
400	Maximum 20 keys reached
401	Unauthenticated session
429	Creation limit exceeded (10/h)

---

See also: Overview | Authentication | Queens | Evaluations