API

Projekte und Backup-Token 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"

Entwicklungsumgebung

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"
    }
  ]
}

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, und die Reihenfolge der Liste ist nicht garantiert.

3. Projekt anlegen

Pflichtfelder sind name (höchstens 100 Zeichen) und availability_zone_id. Optional sind alert_email, billing_reference, 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,
    "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"
  }
}

Das Geheimnis erscheint nur in dieser Antwort

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.

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,
    "immutable_storage": false,
    "retention_days": null,
    "created_at": "2026-09-24 09:41:12.418273"
  },
  "write_tokens_revoked": 1
}

Was Sie wissen sollten

Rechte je Aktion

Die API prüft dieselben Rollen wie das Portal:

Aktion	Rolle
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

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

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
`429`	`rate_limited`	Ratenbegrenzung — `Retry-After` beachten
`500`	`internal_error`	unerwarteter Fehler auf der Plattform
`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 sowie Backup-Token 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…

Schlüssel anlegen​

Schlüssel gegen ein Zugriffstoken tauschen​

Schritt für Schritt: Projekt und Backup-Token anlegen​

1. Zonen abfragen​

2. Organisation ermitteln​

3. Projekt anlegen​

4. Backup-Token anlegen​

5. Token auflisten​

6. Token widerrufen​

7. Projekt schließen​

Was Sie wissen sollten​

Rechte je Aktion​

404 statt 403​

Zonen-Veröffentlichung ist asynchron​

Schließen eines Projekts​

Ratenbegrenzung​

Fehlerformat​

Terraform​

Referenz​