Hop til hovedindhold

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"
Udviklingsmiljø

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
}
}
Hemmeligheden vises kun i dette svar

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:

HandlingRolle
Læse en organisation (betalingsmetode, maskeret mandat)enhver rolle i organisationen undtagen member
Læse projekt, vise tokensenhver rolle i projektet
Ændre projekt, oprette tokenowner, admin, writer
Tilbagekalde tokenowner, admin
Oprette projekt, lukke projektowner eller admin i organisationen
Invitere og fjerne medlemmerowner eller admin i organisationen
Ændre en rolle i organisationenowner i organisationen
Vise medlemmer og grupper, ændre grupperowner 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ænseVærdiGælder for
Forespørgsler pr. IP-adresse60/minutenhver forespørgsel til API'et
Forespørgsler pr. servicekonto60/minutenhver godkendt forespørgsel
Størrelse på én forespørgsel1 MBdet 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.

StatusKodeBetydning
400invalid_requestindholdet er ikke JSON, et obligatorisk felt mangler eller en værdi er ugyldig
400invalid_zoneavailability_zone_id er ukendt eller zonen er ikke active
400retention_out_of_rangeretention_days ligger uden for 1 til 365
401invalid_tokenadgangstoken mangler, er ugyldigt eller udløbet, servicekonto slettet
403owner_inactivedet menneske, der ejer servicekontoen, er deaktiveret
403permission_deniedjeres rolle tillader ikke denne handling
404not_foundressourcen er ukendt eller ikke synlig for jer
405method_not_allowedstien findes, HTTP-metoden gør ikke
409organization_closedorganisationen er ved at blive lukket eller er lukket
409project_closedprojektet er closed, eller closing og der blev bedt om et skrivetoken
409already_memberpersonen tilhører allerede organisationen
409not_org_memberkun organisationens medlemmer kan komme i dens grupper — invitér først
409last_ownerorganisationen eller en owner-gruppe ville miste sin sidste owner
409project_last_owneret projekt ville miste sin sidste owner
409owner_groupet projekts owner-gruppe forbliver, som den er
409group_not_emptykun en tom gruppe kan slettes
422user_not_registeredder findes ingen lionbackup-konto til denne adresse
429rate_limitedhastighedsgrænse — respektér Retry-After
500internal_erroruventet fejl på platformen
502identity_provider_errorbrugeradministrationen har ikke overtaget ændringen, eller kun en del af den — læs den aktuelle tilstand, og prøv igen
503service_unavailablemidlertidigt 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…