API
Projekte, Backup-Token, Mitglieder und Berechtigungen lassen sich nicht nur im
Portal verwalten, sondern auch über eine HTTP-API — für Ihre eigene Automatisierung oder über den
Terraform-Provider. Die API spricht JSON, ist unter
https://api.lionbackup.cloud/api/v1 erreichbar und verwendet dieselbe
Rechteprüfung wie das Portal.
Schlüssel anlegen
Im Portal unter Entwickler legen Sie ein Dienstkonto an und dazu einen API-Schlüssel. Der Schlüssel wird genau einmal angezeigt — bewahren Sie ihn sicher auf.
Ein Dienstkonto hat exakt die Rechte des Menschen, dem es gehört. Wer im Portal keine Projekte anlegen darf, kann das auch über die API nicht; wird das Konto deaktiviert oder der Schlüssel gelöscht, ist der Zugang sofort zu.
Schlüssel gegen ein Zugriffstoken tauschen
Der Schlüssel ist kein Bearer-Token: Sie tauschen ihn zunächst gegen ein kurzlebiges Zugriffstoken (JWT, 15 Minuten gültig).
ACCESS_TOKEN=$(curl -s https://authentik.prod.lionbackup.cloud/application/o/token/ \
-d grant_type=client_credentials \
-d client_id=lionbackup-api \
-d client_secret="$LIONBACKUP_API_KEY" \
-d scope="profile lionbackup_api" | jq -r .access_token)
Verwenden Sie für den Tausch immer den Host authentik.prod.lionbackup.cloud:
der kurze Name authentik.lionbackup.cloud antwortet mit einer Umleitung, und
einer Umleitung folgt ein POST nicht — der Aufruf liefert dann kein Token.
Danach senden Sie das Token als Authorization-Kopfzeile:
API=https://api.lionbackup.cloud/api/v1
curl -s "$API/organizations" -H "Authorization: Bearer $ACCESS_TOKEN"
Für die Entwicklungsumgebung gelten https://api.dev.lionbackup.cloud/api/v1
und https://authentik.dev.lionbackup.cloud/application/o/token/. Ein
Schlüssel gilt nur in der Umgebung, in der er angelegt wurde.
Schritt für Schritt: Projekt und Backup-Token anlegen
Die folgenden Aufrufe bauen aufeinander auf und setzen ACCESS_TOKEN und API
aus dem vorigen Abschnitt voraus. Die Kennungen in den Antworten sind
Beispiele.
1. Zonen abfragen
Ein Projekt braucht die Kennung (UUID) der Zone, in der seine Daten liegen
sollen. Buchbar sind nur Zonen mit status = active.
curl -s "$API/zones" -H "Authorization: Bearer $ACCESS_TOKEN"
{
"zones": [
{
"id": "3f0c2a4e-8b1d-4c6a-9e2f-5d7b1a9c0e31",
"name": "de01-1",
"status": "active",
"provider": "Hetzner",
"location_city": "Nürnberg",
"storage_type": "managed object storage"
},
{
"id": "7a9d4b2c-1e5f-4a83-b6c0-2f8e9d1c4a57",
"name": "de01-2",
"status": "preparing",
"provider": "Hetzner",
"location_city": "Falkenstein",
"storage_type": "managed object storage"
}
]
}
Die Kennung der gewünschten Zone lässt sich direkt in eine Variable übernehmen:
ZONE_ID=$(curl -s "$API/zones" -H "Authorization: Bearer $ACCESS_TOKEN" \
| jq -r '.zones[] | select(.name == "de01-1") | .id')
2. Organisation ermitteln
Projekte gehören zu einer Organisation. Die Liste zeigt jede Organisation, in
der Sie Mitglied sind, samt Ihrer Rolle — Projekte anlegen dürfen owner und
admin.
curl -s "$API/organizations" -H "Authorization: Bearer $ACCESS_TOKEN"
{
"organizations": [
{
"id": "9b2e6c1a-4d3f-4e8b-a7c5-0f1d2e3a4b5c",
"name": "Beispiel GmbH",
"status": "approved",
"role": "owner",
"payment_method": "transfer"
}
]
}
ORG_ID=$(curl -s "$API/organizations" -H "Authorization: Bearer $ACCESS_TOKEN" \
| jq -r '.organizations[] | select(.name == "Beispiel GmbH") | .id')
Die Auswahl über den Namen ist Absicht: Das Dienstkonto sieht alle Organisationen seines Besitzers, nach Namen sortiert, und jede neue Organisation verschiebt die Positionen.
payment_method sagt, wie die Organisation ihre Rechnungen bezahlt: sepa_debit, solange ein SEPA-Lastschriftmandat aktiv ist, sonst transfer. Wo Ihre Rolle nur member ist, fehlt das Feld: Diese Rolle sieht auch im Portal keine Zahlungsdaten. GET /organizations/{orgId} liefert eine Organisation mit ihrem Mandat, die IBAN maskiert.
3. Projekt anlegen
Pflichtfelder sind name (höchstens 100 Zeichen) und availability_zone_id.
Optional sind alert_email, billing_reference, anomaly_detection (Standard
false), immutable_storage (Standard false) und — nur bei unveränderbarer
Ablage — retention_days (1 bis 365, Standard 30).
curl -s -X POST "$API/organizations/$ORG_ID/projects" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d "{\"name\":\"web-servers\",\"availability_zone_id\":\"$ZONE_ID\",\"alert_email\":\"ops@example.com\"}"
Antwort mit Status 201:
{
"project": {
"id": "ea1296ad-5c7b-4f2e-8a1d-3b6c9e0f7d24",
"name": "web-servers",
"status": "active",
"organization_id": "9b2e6c1a-4d3f-4e8b-a7c5-0f1d2e3a4b5c",
"availability_zone_id": "3f0c2a4e-8b1d-4c6a-9e2f-5d7b1a9c0e31",
"alert_email": "ops@example.com",
"billing_reference": null,
"anomaly_detection": false,
"anomaly_phase": null,
"immutable_storage": false,
"retention_days": null,
"created_at": "2026-09-24 09:41:12.418273"
}
}
PROJECT_ID=ea1296ad-5c7b-4f2e-8a1d-3b6c9e0f7d24
4. Backup-Token anlegen
Ein Backup-Token gehört zu genau einem Projekt. Mit type = write sichert
der Client, mit type = read stellt er wieder her. Ohne Angabe entsteht ein
Write-Token für Linux; operating_system kennt Linux, Windows und macOS.
Optional begrenzen usage_count_limit, rate_limit_per_minute und
rate_limit_per_hour die Nutzung.
curl -s -X POST "$API/projects/$PROJECT_ID/tokens" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"type":"write","operating_system":"Linux"}'
Antwort mit Status 201:
{
"token": {
"id": "c4d1e8f2-6a3b-4c9d-8e7f-1a2b3c4d5e6f",
"type": "write",
"secret": "9f3e7b1c…a41c",
"zone_ready": false
}
}
secret ist das eigentliche Backup-Token (128 hexadezimale Zeichen). Es wird
genau einmal ausgeliefert und lässt sich später nicht mehr abrufen — die
Plattform speichert nur einen Hash. Legen Sie es sofort in Ihrem
Geheimnis-Manager ab.
Die Speicherzone kennt ein neues Token erst, wenn sie es übernommen hat,
meist nach weniger als einer Sekunde; bis dahin weist sie es ab. Den Stand
zeigt zone_ready: false heißt noch nicht übernommen, true übernommen.
Wer direkt nach dem Anlegen sichern will, fragt die Token-Liste (Schritt 5)
ab, bis das Token true meldet. Bei null bestätigt die Zone keine Token,
dann gibt es nichts abzuwarten. Der Terraform-Provider wartet ab Version
0.1.5 selbst.
Ein Read-Token für Wiederherstellungen entsteht auf demselben Weg:
curl -s -X POST "$API/projects/$PROJECT_ID/tokens" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"type":"read"}'
{
"token": {
"id": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9",
"type": "read",
"secret": "d27c0a8e…5b93"
}
}
5. Token auflisten
Die Liste enthält nur Metadaten — nie ein Geheimnis. Widerrufene Token erscheinen nicht mehr.
curl -s "$API/projects/$PROJECT_ID/tokens" -H "Authorization: Bearer $ACCESS_TOKEN"
{
"tokens": [
{
"id": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9",
"type": "read",
"operating_system": "Linux",
"is_active": true,
"usage_count": 0,
"usage_count_limit": null,
"created_at": "2026-09-24 09:43:05.102944",
"expire": null
},
{
"id": "c4d1e8f2-6a3b-4c9d-8e7f-1a2b3c4d5e6f",
"type": "write",
"operating_system": "Linux",
"is_active": true,
"usage_count": 0,
"usage_count_limit": null,
"created_at": "2026-09-24 09:42:37.556210",
"expire": null
}
]
}
6. Token widerrufen
TOKEN_ID=c4d1e8f2-6a3b-4c9d-8e7f-1a2b3c4d5e6f
curl -s -X DELETE "$API/projects/$PROJECT_ID/tokens/$TOKEN_ID" \
-H "Authorization: Bearer $ACCESS_TOKEN"
{ "deleted": true }
7. Projekt schließen
Ein Projekt wird nicht gelöscht, sondern geschlossen: der Status wechselt auf
closing, alle Write-Token werden sofort widerrufen, die Antwort nennt deren
Anzahl. Der Aufruf ist idempotent — ein bereits geschlossenes Projekt antwortet
erneut mit 200.
curl -s -X POST "$API/projects/$PROJECT_ID/close" \
-H "Authorization: Bearer $ACCESS_TOKEN"
{
"project": {
"id": "ea1296ad-5c7b-4f2e-8a1d-3b6c9e0f7d24",
"name": "web-servers",
"status": "closing",
"organization_id": "9b2e6c1a-4d3f-4e8b-a7c5-0f1d2e3a4b5c",
"availability_zone_id": "3f0c2a4e-8b1d-4c6a-9e2f-5d7b1a9c0e31",
"alert_email": "ops@example.com",
"billing_reference": null,
"anomaly_detection": false,
"anomaly_phase": null,
"immutable_storage": false,
"retention_days": null,
"created_at": "2026-09-24 09:41:12.418273"
},
"write_tokens_revoked": 1
}
Mitglieder und Berechtigungen
Was Sie im Portal auf der Seite Berechtigungen erledigen, geht auch über
die API, mit denselben Regeln: Mitglieder einladen und entfernen, ihre Rolle in
der Organisation ändern, Berechtigungsgruppen anlegen und füllen. Eine Person
erkennt die API an ihrer numerischen Kennung (id), die die Mitgliederliste
nennt.
Jede Änderung steht im Protokoll der Organisation, gekennzeichnet mit
"via": "api". Eine Änderung an einer Gruppe, die zu einem Projekt gehört,
erscheint zusätzlich im Protokoll dieses Projekts.
Mitglieder auflisten
curl -s "$API/organizations/$ORG_ID/members" -H "Authorization: Bearer $ACCESS_TOKEN"
{
"members": [
{
"id": 1042,
"email": "anna@example.com",
"name": "Anna Berg",
"role": "owner"
},
{
"id": 1077,
"email": "tim@example.com",
"name": "Tim Kurz",
"role": "member"
}
]
}
role ist die Rolle in der Organisation. Jede Rolle außer member gilt für
alle Projekte der Organisation; member gewährt allein nichts, die Rechte
kommen dann aus Berechtigungsgruppen.
Mitglied einladen und Rolle ändern
Eingeladen werden kann nur, wer bereits ein lionbackup-Konto hat. Die Person
kommt als member dazu.
curl -s -X POST "$API/organizations/$ORG_ID/members" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"email":"tim@example.com"}'
Die Rolle in der Organisation ändert nur ein owner:
curl -s -X PATCH "$API/organizations/$ORG_ID/members/1077" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"role":"reader"}'
DELETE /organizations/{orgId}/members/{id} entfernt eine Person ganz aus der
Organisation, aus allen ihren Rollen und Gruppen dort. Der letzte owner einer
Organisation bleibt, und kein Projekt verliert seinen letzten Owner (409).
Berechtigungsgruppe anlegen und füllen
Eine Gruppe gibt ihren Mitgliedern eine Rolle (level) auf dem Projekt, an das
sie gebunden ist. Gebunden wird beim Anlegen über project_id.
GROUP_ID=$(curl -s -X POST "$API/organizations/$ORG_ID/permission-groups" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d "{\"name\":\"Restore-Team\",\"level\":\"reader\",\"project_id\":\"$PROJECT_ID\"}" \
| jq -r .permission_group.id)
curl -s -X PUT "$API/organizations/$ORG_ID/permission-groups/$GROUP_ID/members/1077" \
-H "Authorization: Bearer $ACCESS_TOKEN"
{ "added": true }
Der zweite gleiche Aufruf antwortet mit "added": false und ändert nichts. Mit
PATCH ändern Sie Name und Stufe einer Gruppe, mit DELETE entfernen Sie ein
Mitglied (…/members/{id}) oder die leere Gruppe selbst.
GET /organizations/{orgId}/permission-groups listet die Gruppen mit ihren
Projekten und Mitgliedern.
Eine Gruppe ohne project_id ist an kein Projekt gebunden und gewährt deshalb
keine Projektrolle. Die Owner-Gruppe eines
Projekts legt lionbackup selbst an; sie lässt sich weder umbenennen noch
herabstufen oder löschen (409 owner_group), und ihr letztes Mitglied bleibt
(409 last_owner). Für einen Wechsel nehmen Sie den neuen Owner zuerst auf.
Was Sie wissen sollten
Rechte je Aktion
Die API prüft dieselben Rollen wie das Portal:
| Aktion | Rolle |
|---|---|
| Organisation lesen (Zahlungsart, Mandat maskiert) | jede Rolle in der Organisation außer member |
| Projekt lesen, Token auflisten | jede Rolle im Projekt |
| Projekt ändern, Token anlegen | owner, admin, writer |
| Token widerrufen | owner, admin |
| Projekt anlegen, Projekt schließen | owner oder admin der Organisation |
| Mitglieder einladen und entfernen | owner oder admin der Organisation |
| Rolle in der Organisation ändern | owner der Organisation |
| Mitglieder und Gruppen auflisten, Gruppen ändern | owner oder admin der Organisation; owner eines Projekts für dessen Gruppen |
404 statt 403
Eine Ressource, die es nicht gibt, und eine, auf die Sie keine Rolle haben,
antworten gleich: 404 mit {"error":"not_found"}. So verrät die API nicht,
welche Kennungen existieren. Ein 403 mit permission_denied bekommen Sie
nur, wenn Sie die Ressource sehen dürfen, die Aktion aber nicht.
Zonen-Veröffentlichung ist asynchron
Ein neues Token wird nach dem Anlegen an die Storage-Zone übertragen. Bis das
geschehen ist, weist die Zone das Token mit 401 ab — in der Regel Sekunden,
im Störfall bis zum nächsten Abgleich. Legen Sie das Token dann nicht neu
an, sondern versuchen Sie es später erneut. Umgekehrt kann ein widerrufenes
Token in der Zone kurz weiter gültig sein.
Schließen eines Projekts
Schließen widerruft alle Write-Token sofort; das Projekt steht dann auf
closing. Read-Token bleiben während der Vorhaltezeit gültig, und solange noch
ein Backup in der Vorhaltezeit liegt, lassen sich auch neue Read-Token anlegen,
damit Sie gespeicherte Backups weiterhin wiederherstellen können. Neue
Write-Token lehnt ein Projekt im Status closing ab (409 project_closed);
ist es closed, nimmt es gar keine Token mehr an. Ebenso lehnt eine
geschlossene Organisation neue Projekte ab (409 organization_closed).
Anomalieerkennung
Mit "anomaly_detection": true schalten Sie die Anomalieerkennung für ein
Projekt ein, beim Anlegen oder nachträglich; es ist dieselbe Einstellung wie in
den Projekteinstellungen des Portals. Sie lernt aus den ersten drei Backups den
Rhythmus des Projekts und meldet danach ungewöhnliche Größen, Laufzeiten und
Dateianzahlen, ausgebliebene oder zusätzliche Backups sowie unverschlüsselte
Archive als Nachricht im Portal.
curl -s -X PATCH "$API/projects/$PROJECT_ID" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"anomaly_detection":true}'
Der Wert muss ein JSON-Boolean sein; "true", 1 oder null beantwortet die
API mit 400 invalid_request. Das Feld anomaly_phase zeigt, wo die Erkennung
steht: learning, monitored, paused (solange das Projekt geschlossen wird
oder die Organisation gesperrt ist), ended oder off. Die Erkennung zieht
innerhalb von etwa fünf Minuten nach: Bis sie das Projekt erfasst hat, ist
anomaly_phase null, und nach einer Änderung zeigt das Feld in dieser Zeit
noch den vorigen Stand.
Ratenbegrenzung
| Grenze | Wert | Gilt für |
|---|---|---|
| Anfragen je IP-Adresse | 60/Minute | jede Anfrage an die API |
| Anfragen je Dienstkonto | 60/Minute | jede authentifizierte Anfrage |
| Größe einer Anfrage | 1 MB | der gesendete Inhalt |
Jede authentifizierte Antwort trägt X-RateLimit-Limit,
X-RateLimit-Remaining und X-RateLimit-Reset (Unix-Zeit, zu der das
laufende Minutenfenster endet). Über der Grenze antwortet die API mit 429,
{"error":"rate_limited"} und der Kopfzeile Retry-After — warten Sie diese
Sekunden ab und wiederholen Sie die Anfrage. Der Terraform-Provider tut das von
selbst.
Die X-RateLimit-*-Kopfzeilen können fehlen: fällt der Zähler-Cache der
Plattform aus, zählt die API vorübergehend nicht je Dienstkonto und kündigt
dann auch kein Budget an. Verlassen Sie sich in Ihrer Automatisierung auf den
Status 429 und Retry-After, nicht auf die Kopfzeilen.
Fehlerformat
Jeder Fehler ist ein JSON-Objekt mit genau einem Feld: {"error":"<code>"}.
Der Code ist stabil und für Programme gedacht; verzweigen Sie auf ihn, nicht
auf den HTTP-Status allein.
| Status | Code | Bedeutung |
|---|---|---|
400 | invalid_request | Inhalt ist kein JSON, ein Pflichtfeld fehlt oder ein Wert ist ungültig |
400 | invalid_zone | availability_zone_id ist unbekannt oder die Zone ist nicht active |
400 | retention_out_of_range | retention_days liegt außerhalb von 1 bis 365 |
401 | invalid_token | Zugriffstoken fehlt, ist ungültig oder abgelaufen, Dienstkonto gelöscht |
403 | owner_inactive | der Mensch, dem das Dienstkonto gehört, ist deaktiviert |
403 | permission_denied | Ihre Rolle erlaubt diese Aktion nicht |
404 | not_found | Ressource unbekannt oder für Sie nicht sichtbar |
405 | method_not_allowed | der Pfad existiert, die HTTP-Methode nicht |
409 | organization_closed | die Organisation wird geschlossen oder ist geschlossen |
409 | project_closed | Projekt closed, oder closing und ein Write-Token angefragt |
409 | already_member | die Person gehört schon zur Organisation |
409 | not_org_member | nur Mitglieder der Organisation kommen in ihre Gruppen — erst einladen |
409 | last_owner | die Organisation oder eine Owner-Gruppe verlöre ihren letzten Owner |
409 | project_last_owner | ein Projekt verlöre seinen letzten Owner |
409 | owner_group | die Owner-Gruppe eines Projekts bleibt, wie sie ist |
409 | group_not_empty | nur eine leere Gruppe lässt sich löschen |
422 | user_not_registered | zu dieser Adresse gibt es kein lionbackup-Konto |
429 | rate_limited | Ratenbegrenzung — Retry-After beachten |
500 | internal_error | unerwarteter Fehler auf der Plattform |
502 | identity_provider_error | die Benutzerverwaltung hat eine Änderung nicht oder nur teilweise übernommen — Stand lesen, erneut versuchen |
503 | service_unavailable | vorübergehend nicht verfügbar — später erneut versuchen |
Terraform
Für Terraform und OpenTofu gibt es einen Provider, der dieselbe API verwendet und Projekte, Backup-Token, Mitglieder und Berechtigungsgruppen als Ressourcen verwaltet. Bezugsquelle, Einrichtung und ein vollständiges Beispiel finden Sie auf der Seite Terraform.
Referenz
Die vollständige Spezifikation steht als OpenAPI-3.1-Dokument zum Herunterladen
bereit: openapi.yaml. Dieselbe Datei liefert auch
die API selbst unter /api/v1/openapi.yaml aus — sie beschreibt damit immer
genau den Stand, der gerade läuft.
Loading the API reference…