API

Projecten en back-uptokens beheert u niet alleen in het portaal, maar ook via een HTTP-API — voor uw eigen automatisering of via de Terraform-provider. De API spreekt JSON, staat op https://api.lionbackup.cloud/api/v1 en gebruikt precies dezelfde rechtencontrole als het portaal.

Een sleutel aanmaken

In het portaal onder Ontwikkelaars maakt u een serviceaccount aan en daarbij een API-sleutel. De sleutel wordt precies één keer getoond — bewaar hem veilig.

Een serviceaccount heeft exact de rechten van de persoon die hem bezit. Wie in het portaal geen projecten mag aanmaken, kan dat via de API evenmin; wordt het account gedeactiveerd of de sleutel verwijderd, dan is de toegang meteen dicht.

De sleutel inwisselen voor een toegangstoken

De sleutel is geen bearer token: u wisselt hem eerst in voor een kortlevend toegangstoken (een JWT, 15 minuten geldig).

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)

Gebruik voor het inwisselen altijd de host authentik.prod.lionbackup.cloud: de korte naam authentik.lionbackup.cloud antwoordt met een omleiding, en een POST volgt geen omleiding — de aanroep levert dan geen token op.

Daarna stuurt u het token als Authorization-header mee:

API=https://api.lionbackup.cloud/api/v1

curl -s "$API/organizations" -H "Authorization: Bearer $ACCESS_TOKEN"

Ontwikkelomgeving

Voor de ontwikkelomgeving gelden https://api.dev.lionbackup.cloud/api/v1 en https://authentik.dev.lionbackup.cloud/application/o/token/. Een sleutel geldt alleen in de omgeving waarin hij is aangemaakt.

Stap voor stap: een project en een back-uptoken aanmaken

De volgende aanroepen bouwen op elkaar voort en gaan uit van ACCESS_TOKEN en API uit de vorige paragraaf. De identifiers in de antwoorden zijn voorbeelden.

1. Zones opvragen

Een project heeft de identifier (UUID) nodig van de zone waarin zijn data moet liggen. Alleen zones met status = active zijn te boeken.

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

De identifier van de gewenste zone kunt u direct in een variabele overnemen:

ZONE_ID=$(curl -s "$API/zones" -H "Authorization: Bearer $ACCESS_TOKEN" \
  | jq -r '.zones[] | select(.name == "de01-1") | .id')

2. De organisatie bepalen

Projecten horen bij een organisatie. De lijst toont elke organisatie waarvan u lid bent, inclusief uw rol — projecten aanmaken mogen owner en admin.

curl -s "$API/organizations" -H "Authorization: Bearer $ACCESS_TOKEN"

{
  "organizations": [
    {
      "id": "9b2e6c1a-4d3f-4e8b-a7c5-0f1d2e3a4b5c",
      "name": "Example Ltd",
      "status": "approved",
      "role": "owner"
    }
  ]
}

ORG_ID=$(curl -s "$API/organizations" -H "Authorization: Bearer $ACCESS_TOKEN" \
  | jq -r '.organizations[] | select(.name == "Example Ltd") | .id')

De keuze op naam is bewust: het serviceaccount ziet alle organisaties van zijn eigenaar en de volgorde van de lijst is niet gegarandeerd.

3. Een project aanmaken

Verplichte velden zijn name (maximaal 100 tekens) en availability_zone_id. Optioneel zijn alert_email, billing_reference, immutable_storage (standaard false) en — alleen bij onveranderbare opslag — retention_days (1 tot 365, standaard 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\"}"

Antwoord met 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. Een back-uptoken aanmaken

Een back-uptoken hoort bij precies één project. Met type = write maakt de client back-ups, met type = read herstelt hij. Zonder opgave ontstaat een schrijftoken voor Linux; operating_system kent Linux, Windows en macOS. Optioneel beperken usage_count_limit, rate_limit_per_minute en rate_limit_per_hour het gebruik.

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

Antwoord met status 201:

{
  "token": {
    "id": "c4d1e8f2-6a3b-4c9d-8e7f-1a2b3c4d5e6f",
    "type": "write",
    "secret": "9f3e7b1c…a41c"
  }
}

Het geheim verschijnt alleen in dit antwoord

secret is het eigenlijke back-uptoken (128 hexadecimale tekens). Het wordt precies één keer uitgeleverd en is later niet meer op te vragen — het platform bewaart alleen een hash. Sla het meteen op in uw geheimenbeheer.

Een leestoken voor herstel ontstaat op dezelfde manier:

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. Tokens opsommen

De lijst bevat alleen metadata — nooit een geheim. Ingetrokken tokens verschijnen niet meer.

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. Een token intrekken

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. Een project sluiten

Een project wordt niet verwijderd, maar gesloten: de status gaat naar closing, alle schrijftokens worden meteen ingetrokken en het antwoord noemt hun aantal. De aanroep is idempotent — een al gesloten project antwoordt opnieuw met 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
}

Wat u moet weten

Rechten per actie

De API controleert dezelfde rollen als het portaal:

Actie	Rol
Project lezen, tokens opsommen	elke rol in het project
Project wijzigen, token aanmaken	owner, admin, writer
Token intrekken	owner, admin
Project aanmaken, project sluiten	owner of admin van de organisatie

404 in plaats van 403

Een resource die niet bestaat en een resource waarop u geen rol hebt, antwoorden hetzelfde: 404 met {"error":"not_found"}. Zo verraadt de API niet welke identifiers bestaan. Een 403 met permission_denied krijgt u alleen als u de resource mag zien, maar de actie niet mag uitvoeren.

Publicatie naar de zone is asynchroon

Een nieuw token wordt na het aanmaken overgedragen aan de Storage Zone. Tot dat is gebeurd, wijst de zone het token af met 401 — doorgaans enkele seconden, bij een storing tot aan de volgende synchronisatie. Maak het token dan niet opnieuw aan, maar probeer het later nog eens. Omgekeerd kan een ingetrokken token in de zone nog kort geldig blijven.

Een project sluiten

Sluiten trekt alle schrijftokens meteen in en zet het project op closing. Leestokens blijven tijdens de bewaartermijn geldig, en zolang er nog een back-up binnen de bewaartermijn valt, kunt u ook nieuwe leestokens aanmaken om opgeslagen back-ups te blijven herstellen. Een project in closing weigert nieuwe schrijftokens (409 project_closed); zodra het closed is, neemt het helemaal geen tokens meer aan. Evenzo weigert een gesloten organisatie nieuwe projecten (409 organization_closed).

Snelheidslimieten

Limiet	Waarde	Geldt voor
Verzoeken per IP-adres	60/minuut	elk verzoek aan de API
Verzoeken per serviceaccount	60/minuut	elk geauthenticeerd verzoek
Grootte van één verzoek	1 MB	de verzonden inhoud

Elk geauthenticeerd antwoord draagt X-RateLimit-Limit, X-RateLimit-Remaining en X-RateLimit-Reset (Unix-tijd waarop het lopende minuutvenster eindigt). Boven de limiet antwoordt de API met 429, {"error":"rate_limited"} en de header Retry-After — wacht dat aantal seconden en herhaal het verzoek. De Terraform-provider doet dat vanzelf.

De X-RateLimit-*-headers kunnen ontbreken: valt de tellercache van het platform uit, dan telt de API tijdelijk niet per serviceaccount en kondigt dan ook geen budget aan. Vertrouw in uw automatisering op de status 429 en Retry-After, niet op de headers.

Foutformaat

Elke fout is een JSON-object met precies één veld: {"error":"<code>"}. De code is stabiel en bedoeld voor programma's; vertak op de code, niet alleen op de HTTP-status.

Status	Code	Betekenis
400	invalid_request	inhoud is geen JSON, een verplicht veld ontbreekt of een waarde is ongeldig
400	invalid_zone	availability_zone_id is onbekend of de zone is niet active
400	retention_out_of_range	retention_days ligt buiten 1 tot 365
401	invalid_token	toegangstoken ontbreekt, is ongeldig of verlopen, serviceaccount verwijderd
403	owner_inactive	de persoon die het serviceaccount bezit, is gedeactiveerd
403	permission_denied	uw rol staat deze actie niet toe
404	not_found	resource onbekend of voor u niet zichtbaar
405	method_not_allowed	het pad bestaat, de HTTP-methode niet
409	organization_closed	de organisatie wordt gesloten of is gesloten
409	project_closed	het project is closed, of closing en er werd een schrijftoken gevraagd
429	rate_limited	snelheidslimiet — let op Retry-After
500	internal_error	onverwachte fout op het platform
503	service_unavailable	tijdelijk niet beschikbaar — probeer het later opnieuw

Terraform

Voor Terraform en OpenTofu is er een provider die dezelfde API gebruikt en projecten en back-uptokens als resources beheert. Het bronadres, de inrichting en een volledig voorbeeld vindt u op de pagina Terraform.

Referentie

De volledige specificatie is als OpenAPI 3.1-document te downloaden: openapi.yaml. De API levert hetzelfde bestand op /api/v1/openapi.yaml — het beschrijft dus altijd precies de versie die draait.

Loading the API reference…