The lionbackup API

Create projects, issue and revoke backup tokens, query zones and organizations: a REST API with JSON, an open OpenAPI 3.1 specification and a Terraform provider. It applies the same permissions as the portal.

Your first call in three steps

1. Create a service account and a key

   In the portal under Developer you create a service account and an API key for it. The service account has exactly the permissions of your user account; the key is shown only once.

2. Exchange the key for an access token

   The key is not a bearer token. You exchange it for an access token that is valid for 15 minutes:

   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)

3. Send requests with the token

   All endpoints live under https://api.lionbackup.cloud/api/v1 and expect the token in the Authorization header:

   API=https://api.lionbackup.cloud/api/v1
   
   curl -s "$API/organizations" -H "Authorization: Bearer $ACCESS_TOKEN"
   
   # 200
   {"organizations": [{
     "id": "9b2e6c1a-…", "name": "Example Ltd",
     "status": "approved", "role": "owner"
   }]}

Example: create a project and issue a write token

A project needs a name and the ID of its storage zone. A backup token belongs to exactly one project: the client backs up with a write token and restores with a read token.

# Pick a zone: only zones with status "active" can be used
ZONE_ID=$(curl -s "$API/zones" -H "Authorization: Bearer $ACCESS_TOKEN" \
  | jq -r '.zones[] | select(.name == "de01-1") | .id')

# Create the project (role owner or admin in the organization)
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\"}"

# 201
{"project": {
  "id": "ea1296ad-…", "name": "web-servers", "status": "active",
  "availability_zone_id": "b0000001-…", "alert_email": null, …
}}

# Issue a write token for the client
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"}'

# 201: "secret" is the backup token and appears only in this response
{"token": {"id": "c4d1e8f2-…", "type": "write", "secret": "9f3e7b1c…"}}

Responses and IDs are shown shortened. A project is not deleted but closed with POST /projects/{projectId}/close: write tokens are revoked immediately, read tokens stay valid for restores during the retention period.

All endpoints

Good to know

Specification and Terraform

Questions about the API? Reach us via the contact form.