API

Projekter og backup-tokens 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"
    }
  ]
}

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, og listens rækkefølge er ikke garanteret.

3. Opret et projekt

Obligatoriske felter er name (højst 100 tegn) og availability_zone_id. Valgfrie er alert_email, billing_reference, 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,
    "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"
  }
}

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.

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

Hvad I bør vide

Rettigheder per handling

API'et kontrollerer de samme roller som portalen:

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

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

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
`429`	`rate_limited`	hastighedsgrænse — respektér `Retry-After`
`500`	`internal_error`	uventet fejl på platformen
`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 og backup-tokens 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…

Opret en nøgle​

Byt nøglen til et adgangstoken​

Trin for trin: opret et projekt og et backup-token​

1. Hent zonerne​

2. Find organisationen​

3. Opret et projekt​

4. Opret et backup-token​

5. Vis tokens​

6. Tilbagekald et token​

7. Luk projektet​

Hvad I bør vide​

Rettigheder per handling​

404 i stedet for 403​

Udrulning til zonen er asynkron​

Lukning af et projekt​

Hastighedsgrænser​

Fejlformat​

Terraform​

Reference​