API-Schlüssel

API-Schlüssel ermöglichen den Zugriff auf Ihre BeePass-Daten aus externen Anwendungen, Skripten oder Drittanbieter-Integrationen ohne die Weboberfläche. Jeder Schlüssel verfügt über granulare Berechtigungen pro Ressource.

Funktionsweise

[Ihre Anwendung]
    │ Authorization: Bearer bp_live_a3f8...5e82
    ▼
https://beepass.io/api/v1/queens
    │ SHA-256-Validierung → DB-Lookup → Berechtigungsprüfung
    ▼
[JSON-Daten zurückgegeben]

1. Erstellen Sie einen Schlüssel über die Weboberfläche (Avatar-Menü → API-Schlüssel)
2. Kopieren Sie den Schlüssel — er wird nur einmal angezeigt
3. Verwenden Sie ihn im Authorization-Header Ihrer Anfragen

Schlüsselformat

bp_live_ + 64 hexadezimale Zeichen = 72 Zeichen

Beispiel: bp_live_a3f8e2b1c4d5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1

Sicherheit

Der Rohschlüssel wird nur einmal bei der Erstellung angezeigt. BeePass speichert nur einen SHA-256-Hash — es ist unmöglich, einen verlorenen Schlüssel wiederherzustellen. Sie müssen einen neuen erstellen.

Verwendung

Fügen Sie den Schlüssel zum Authorization-Header jeder Anfrage hinzu:

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()

Berechtigungen

Jeder Schlüssel definiert eine Zugriffsebene pro Ressource:

Ressource	Beschreibung
Königinnen	F0- und F1-Königinnen (Zuchtmaterial, Produktion)
Bewertungen	Leistungsbewertungen
BLUP	Geschätzte Zuchtwerte (EBV)
Bienenstand	Bienenstände und Bienenstöcke
Konto	Profil- und Kontoeinstellungen

Berechtigungsstufen

Stufe	Lesen (GET)	Schreiben (POST/PUT/DELETE)
Keine	-	-
Lesen	Ja	-
Schreiben	Ja	Ja

tipp

Die Stufe Schreiben beinhaltet automatisch Lesezugriff. Es ist nicht nötig, beides festzulegen.

Voreingestellte Vorlagen

Vorlage	Beschreibung	Berechtigungen
Nur lesen	Alle Daten einsehen	Alle Ressourcen im Lesemodus
Bewerter	Feldbewertungseingabe	Bewertungen schreibbar, Rest lesbar (außer Bienenstand)
Benutzerdefiniert	Manuelle Konfiguration	Sie wählen jede Berechtigung

Einschränkungen

Ablauf (TTL)

Legen Sie eine Lebensdauer für Ihren Schlüssel fest:

Option	Beschreibung
7 Tage	Tests und Entwicklung
30 Tage	Temporäre Integrationen
90 Tage	Standardnutzung
365 Tage	Langzeitintegrationen
Nie	Kein automatischer Ablauf

Ein abgelaufener Schlüssel wird automatisch abgelehnt. Er bleibt in der Liste mit dem Status "Abgelaufen" sichtbar.

IP-Einschränkung

Beschränken Sie die Schlüsselnutzung auf bestimmte IP-Adressen für erhöhte Sicherheit:

• Einzelne IP: 203.0.113.5
• CIDR-Subnetz: 192.168.1.0/24

Ohne IP-Einschränkung kann der Schlüssel von jeder Adresse verwendet werden.

info

Die IP-Einschränkung wird bei jeder Anfrage überprüft. Die Client-IP wird aus den Headern CF-Connecting-IP, X-Forwarded-For oder X-Real-IP extrahiert.

Schlüsselverwaltung

Schlüssel erstellen

Rufen Sie die Seite API-Schlüssel über das Avatar-Menü im Header auf und klicken Sie auf Schlüssel generieren. Der 4-Schritte-Assistent führt Sie:

1. Name — Wählen Sie einen beschreibenden Namen und eine Berechtigungsvorlage
2. Berechtigungen — Passen Sie die Berechtigungen pro Ressource an (benutzerdefinierter Modus)
3. Einschränkungen — Legen Sie Ablauf und erlaubte IPs fest
4. Generierter Schlüssel — Kopieren Sie Ihren Schlüssel sofort

Deaktivieren / Reaktivieren

Verwenden Sie den Schalter in der Spalte "Aktivieren", um einen Schlüssel vorübergehend zu deaktivieren, ohne ihn zu löschen. Ein deaktivierter Schlüssel wird sofort von der API abgelehnt.

Widerrufen

Klicken Sie auf das Papierkorb-Symbol und bestätigen Sie den Widerruf. Der Schlüssel wechselt in den Status "Widerrufen" und kann nicht reaktiviert werden.

Grenzen

Grenze	Wert
Max. Schlüssel pro Benutzer	20
Erstellungen pro Stunde	10
Namenslänge	1 bis 100 Zeichen

Verwaltungs-API

Schlüssel werden über die Standard-REST-API verwaltet (Supabase-Session-Authentifizierung):

Methode	Route	Beschreibung
GET	/api/api-keys	Ihre Schlüssel auflisten (ohne Hash)
POST	/api/api-keys	Neuen Schlüssel erstellen
PUT	/api/api-keys/{id}	Name oder Status aktualisieren
DELETE	/api/api-keys	Schlüssel widerrufen

Schlüssel erstellen (POST)

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

Antwort (201):

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

Schlüssel widerrufen (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" }'

Fehlercodes

Code	Situation
400	Ungültige Parameter (Name, Berechtigungen, TTL, IP)
400	Maximum von 20 Schlüsseln erreicht
401	Nicht authentifizierte Sitzung
429	Erstellungslimit überschritten (10/h)

---

Siehe auch: Übersicht | Authentifizierung | Königinnen | Bewertungen