API
Projekter, backup-tokens, medlemmer og rettigheder kan administreres ikke bare i
portalen, men også via et HTTP-API — til jeres egen automatisering eller gennem
Terraform-provideren. API'et taler JSON, ligger på
https://api.lionbackup.cloud/api/v1 og bruger nøjagtig samme
rettighedskontrol som portalen.
Opret en nøgle
I portalen under Udvikler opretter I en servicekonto og en API-nøgle til den. Nøglen vises præcis én gang — opbevar den sikkert.
En servicekonto har nøjagtig de rettigheder, som det menneske har, der ejer den. Den, der ikke må oprette projekter i portalen, kan det heller ikke via API'et; deaktiveres kontoen eller slettes nøglen, er adgangen lukket med det samme.
Byt nøglen til et adgangstoken
Nøglen er ikke et bearer-token: I bytter den først til et kortlivet adgangstoken (et JWT, gyldigt i 15 minutter).
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)
Brug altid hosten authentik.prod.lionbackup.cloud til byttet: det korte navn
authentik.lionbackup.cloud svarer med en omdirigering, og et POST følger ikke
en omdirigering — kaldet giver så intet token.
Derefter sender I tokenet som Authorization-header:
API=https://api.lionbackup.cloud/api/v1
curl -s "$API/organizations" -H "Authorization: Bearer $ACCESS_TOKEN"
For udviklingsmiljøet gælder https://api.dev.lionbackup.cloud/api/v1 og
https://authentik.dev.lionbackup.cloud/application/o/token/. En nøgle gælder
kun i det miljø, hvor den blev oprettet.
Trin for trin: opret et projekt og et backup-token
De følgende kald bygger oven på hinanden og forudsætter ACCESS_TOKEN og API
fra det foregående afsnit. Id'erne i svarene er eksempler.
1. Hent zonerne
Et projekt har brug for id'et (UUID) på den zone, hvor dets data skal ligge.
Kun zoner med status = active kan bookes.
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"
}
]
}
Id'et på den ønskede zone kan lægges direkte i en variabel:
ZONE_ID=$(curl -s "$API/zones" -H "Authorization: Bearer $ACCESS_TOKEN" \
| jq -r '.zones[] | select(.name == "de01-1") | .id')
2. Find organisationen
Projekter hører til en organisation. Listen viser hver organisation, I er
medlem af, sammen med jeres rolle — owner og admin må oprette projekter.
curl -s "$API/organizations" -H "Authorization: Bearer $ACCESS_TOKEN"
{
"organizations": [
{
"id": "9b2e6c1a-4d3f-4e8b-a7c5-0f1d2e3a4b5c",
"name": "Example Ltd",
"status": "approved",
"role": "owner",
"payment_method": "transfer"
}
]
}
ORG_ID=$(curl -s "$API/organizations" -H "Authorization: Bearer $ACCESS_TOKEN" \
| jq -r '.organizations[] | select(.name == "Example Ltd") | .id')
Valget efter navn er bevidst: servicekontoen ser alle ejerens organisationer sorteret efter navn, og hver ny organisation flytter placeringerne.
payment_method angiver, hvordan organisationen betaler sine fakturaer: sepa_debit, så længe et SEPA Direct Debit-mandat er aktivt, ellers transfer. Hvor jeres rolle kun er member, mangler feltet: den rolle ser heller ingen betalingsdata i portalen. GET /organizations/{orgId} leverer én organisation med dens mandat, IBAN maskeret.
3. Opret et projekt
Obligatoriske felter er name (højst 100 tegn) og availability_zone_id.
Valgfrie er alert_email, billing_reference, anomaly_detection (standard
false), immutable_storage (standard false) og — kun ved uforanderlig
opbevaring — retention_days (1 til 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\"}"
Svar med 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. Opret et backup-token
Et backup-token hører til præcis ét projekt. Med type = write
sikkerhedskopierer klienten, med type = read gendanner den. Uden angivelse
oprettes et skrivetoken til Linux; operating_system kender Linux, Windows
og macOS. Valgfrit begrænser usage_count_limit, rate_limit_per_minute og
rate_limit_per_hour brugen.
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"}'
Svar med status 201:
{
"token": {
"id": "c4d1e8f2-6a3b-4c9d-8e7f-1a2b3c4d5e6f",
"type": "write",
"secret": "9f3e7b1c…a41c",
"zone_ready": false
}
}
secret er selve backup-tokenet (128 hexadecimale tegn). Det udleveres præcis
én gang og kan ikke hentes senere — platformen gemmer kun en hash. Læg det med
det samme i jeres secrets-manager.
Lagringszonen kender først et nyt token, når den har overtaget det, som
regel på under et sekund; indtil da afviser den det. zone_ready viser
status: false betyder endnu ikke overtaget, true overtaget. Vil du tage
backup lige efter oprettelsen, så forespørg tokenlisten (trin 5), indtil
tokenet melder true. Ved null bekræfter zonen ikke tokens, og der er
intet at vente på. Terraform-provideren venter selv fra version 0.1.5.
Et læsetoken til gendannelser oprettes på samme måde:
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. Vis tokens
Listen indeholder kun metadata — aldrig en hemmelighed. Tilbagekaldte tokens vises ikke længere.
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. Tilbagekald et token
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. Luk projektet
Et projekt slettes ikke, men lukkes: status skifter til closing, alle
skrivetokens tilbagekaldes med det samme, og svaret angiver deres antal. Kaldet
er idempotent — et allerede lukket projekt svarer igen med 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
}
Medlemmer og rettigheder
Det, I gør i portalen på siden Rettigheder, kan I også gøre via API'et,
efter de samme regler: invitere og fjerne medlemmer, ændre deres rolle i
organisationen, oprette rettighedsgrupper og tilføje medlemmer til dem. API'et
genkender en person på vedkommendes numeriske id (id), som medlemslisten
viser.
Enhver ændring registreres i organisationens auditlog, markeret med
"via": "api". En ændring i en gruppe, der hører til et projekt, vises desuden
i det pågældende projekts auditlog.
Vis medlemmer
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 er rollen i organisationen. Enhver rolle undtagen member gælder for
alle organisationens projekter; member giver ingen rettigheder i sig selv, og
rettighederne kommer så fra rettighedsgrupper.
Invitér et medlem og ændr rollen
Kun den, der allerede har en lionbackup-konto, kan inviteres. Personen kommer
med som member.
curl -s -X POST "$API/organizations/$ORG_ID/members" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"email":"tim@example.com"}'
Kun en owner ændrer en rolle i organisationen:
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} fjerner en person helt fra
organisationen, fra alle vedkommendes roller og grupper der. En organisation
beholder sin sidste owner, og intet projekt mister sin sidste owner (409).
Opret en rettighedsgruppe og tilføj medlemmer
En gruppe giver sine medlemmer en rolle (level) på det projekt, den er knyttet
til. Den knyttes til projektet ved oprettelsen via 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\":\"Gendannelsesteam\",\"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 }
Gentager I kaldet, svarer API'et "added": false og ændrer intet. PATCH
ændrer en gruppes navn og niveau; DELETE fjerner et medlem (…/members/{id}) eller
selve den tomme gruppe. GET /organizations/{orgId}/permission-groups viser
grupperne med deres projekter og medlemmer.
En gruppe uden project_id er ikke knyttet til noget projekt og giver derfor
ingen projektrolle. lionbackup opretter selv hvert projekts owner-gruppe; den kan
hverken omdøbes, nedgraderes eller slettes (409 owner_group), og dens sidste
medlem bliver (409 last_owner). Vil I overdrage ejerskabet, så tilføj først
den nye owner.
Hvad I bør vide
Rettigheder per handling
API'et kontrollerer de samme roller som portalen:
| Handling | Rolle |
|---|---|
| Læse en organisation (betalingsmetode, maskeret mandat) | enhver rolle i organisationen undtagen member |
| Læse projekt, vise tokens | enhver rolle i projektet |
| Ændre projekt, oprette token | owner, admin, writer |
| Tilbagekalde token | owner, admin |
| Oprette projekt, lukke projekt | owner eller admin i organisationen |
| Invitere og fjerne medlemmer | owner eller admin i organisationen |
| Ændre en rolle i organisationen | owner i organisationen |
| Vise medlemmer og grupper, ændre grupper | owner eller admin i organisationen; owner i et projekt for dets grupper |
404 i stedet for 403
En ressource, der ikke findes, og en, som I ikke har nogen rolle på, svarer
ens: 404 med {"error":"not_found"}. Sådan røber API'et ikke, hvilke id'er
der findes. Et 403 med permission_denied får I kun, når I må se ressourcen,
men ikke må udføre handlingen.
Udrulning til zonen er asynkron
Et nyt token overføres til Storage Zone efter oprettelsen. Indtil det er sket,
afviser zonen tokenet med 401 — som regel sekunder, ved en driftsforstyrrelse
indtil næste synkronisering. Opret ikke tokenet på ny, men prøv igen
senere. Omvendt kan et tilbagekaldt token kortvarigt fortsat være gyldigt i
zonen.
Lukning af et projekt
Lukning tilbagekalder alle skrivetokens med det samme og sætter projektet til
closing. Læsetokens forbliver gyldige i opbevaringsperioden, og så længe en
backup stadig er inden for opbevaringsperioden, kan I også oprette nye
læsetokens og fortsat gendanne gemte backups. Et projekt i status closing
afviser nye skrivetokens (409 project_closed); når det er closed, tager det
slet ikke imod tokens. Ligeledes afviser en lukket organisation nye projekter
(409 organization_closed).
Anomalidetektion
Med "anomaly_detection": true slår I anomalidetektionen til for et projekt,
ved oprettelsen eller senere; det er den samme indstilling som i portalens
projektindstillinger. Den lærer projektets rytme af de første tre backups og
melder derefter usædvanlige størrelser, varigheder og filantal, manglende eller
ekstra backups samt ukrypterede arkiver som beskeder i portalen.
curl -s -X PATCH "$API/projects/$PROJECT_ID" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"anomaly_detection":true}'
Værdien skal være en JSON-boolean; "true", 1 eller null besvarer API'et
med 400 invalid_request. Feltet anomaly_phase viser, hvor detektionen står:
learning, monitored, paused (mens projektet lukkes, eller organisationen
er spærret), ended eller off. Detektionen følger med inden for cirka fem
minutter: indtil den har registreret projektet, er anomaly_phase null, og
efter en ændring viser feltet i mellemtiden stadig den tidligere tilstand.
Hastighedsgrænser
| Grænse | Værdi | Gælder for |
|---|---|---|
| Forespørgsler pr. IP-adresse | 60/minut | enhver forespørgsel til API'et |
| Forespørgsler pr. servicekonto | 60/minut | enhver godkendt forespørgsel |
| Størrelse på én forespørgsel | 1 MB | det indhold, I sender |
Ethvert godkendt svar bærer X-RateLimit-Limit, X-RateLimit-Remaining og
X-RateLimit-Reset (Unix-tid, hvor det løbende minutvindue slutter). Over
grænsen svarer API'et 429 med {"error":"rate_limited"} og headeren
Retry-After — vent det antal sekunder, og prøv igen. Terraform-provideren gør
det af sig selv.
X-RateLimit-*-headerne kan mangle: svigter platformens tæller-cache, tæller
API'et midlertidigt ikke pr. servicekonto og oplyser så heller ikke noget
budget. Stol i jeres automatisering på status 429 og Retry-After, ikke på
headerne.
Fejlformat
Enhver fejl er et JSON-objekt med præcis ét felt: {"error":"<code>"}. Koden
er stabil og beregnet til programmer; forgren på den, ikke på HTTP-status
alene.
| Status | Kode | Betydning |
|---|---|---|
400 | invalid_request | indholdet er ikke JSON, et obligatorisk felt mangler eller en værdi er ugyldig |
400 | invalid_zone | availability_zone_id er ukendt eller zonen er ikke active |
400 | retention_out_of_range | retention_days ligger uden for 1 til 365 |
401 | invalid_token | adgangstoken mangler, er ugyldigt eller udløbet, servicekonto slettet |
403 | owner_inactive | det menneske, der ejer servicekontoen, er deaktiveret |
403 | permission_denied | jeres rolle tillader ikke denne handling |
404 | not_found | ressourcen er ukendt eller ikke synlig for jer |
405 | method_not_allowed | stien findes, HTTP-metoden gør ikke |
409 | organization_closed | organisationen er ved at blive lukket eller er lukket |
409 | project_closed | projektet er closed, eller closing og der blev bedt om et skrivetoken |
409 | already_member | personen tilhører allerede organisationen |
409 | not_org_member | kun organisationens medlemmer kan komme i dens grupper — invitér først |
409 | last_owner | organisationen eller en owner-gruppe ville miste sin sidste owner |
409 | project_last_owner | et projekt ville miste sin sidste owner |
409 | owner_group | et projekts owner-gruppe forbliver, som den er |
409 | group_not_empty | kun en tom gruppe kan slettes |
422 | user_not_registered | der findes ingen lionbackup-konto til denne adresse |
429 | rate_limited | hastighedsgrænse — respektér Retry-After |
500 | internal_error | uventet fejl på platformen |
502 | identity_provider_error | brugeradministrationen har ikke overtaget ændringen, eller kun en del af den — læs den aktuelle tilstand, og prøv igen |
503 | service_unavailable | midlertidigt ikke tilgængelig — prøv igen senere |
Terraform
Til Terraform og OpenTofu findes en provider, der bruger samme API og administrerer projekter, backup-tokens, medlemmer og rettighedsgrupper som ressourcer. Kilde, opsætning og et fuldstændigt eksempel finder I på siden Terraform.
Reference
Den fulde specifikation findes som OpenAPI 3.1-dokument til download:
openapi.yaml. API'et leverer selv samme fil på
/api/v1/openapi.yaml — den beskriver altså altid præcis den version, der
kører.
Loading the API reference…