Saltar al contenido principal

API

Los proyectos, los tokens de copia de seguridad, los miembros y los permisos no solo se gestionan en el portal, sino también a través de una API HTTP — para su propia automatización o mediante el proveedor de Terraform. La API habla JSON, está en https://api.lionbackup.cloud/api/v1 y aplica exactamente la misma comprobación de permisos que el portal.

Crear una clave​

En el portal, en Desarrollo, se crea una cuenta de servicio y una clave de API para ella. La clave se muestra una sola vez — guárdela en un lugar seguro.

Una cuenta de servicio tiene exactamente los permisos de la persona a la que pertenece. Quien no pueda crear proyectos en el portal tampoco podrá hacerlo por la API; al desactivar la cuenta o borrar la clave, el acceso se cierra de inmediato.

Canjear la clave por un token de acceso​

La clave no es un bearer token: primero se canjea por un token de acceso de corta duración (un JWT, válido 15 minutos).

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)

Para el canje utilice siempre el host authentik.prod.lionbackup.cloud: el nombre corto authentik.lionbackup.cloud responde con una redirección, y un POST no sigue las redirecciones — la llamada no devolvería entonces ningún token.

Después se envía el token en la cabecera Authorization:

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

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

Para el entorno de desarrollo rigen https://api.dev.lionbackup.cloud/api/v1 y https://authentik.dev.lionbackup.cloud/application/o/token/. Una clave solo es válida en el entorno en el que fue creada.

Paso a paso: crear un proyecto y un token de copia de seguridad​

Las siguientes llamadas se basan unas en otras y presuponen ACCESS_TOKEN y API de la sección anterior. Los identificadores de las respuestas son ejemplos.

1. Consultar las zonas​

Un proyecto necesita el identificador (UUID) de la zona en la que deben residir sus datos. Solo son contratables las zonas con status = active.

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

El identificador de la zona deseada puede guardarse directamente en una variable:

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

2. Determinar la organización​

Los proyectos pertenecen a una organización. La lista muestra cada organización de la que usted es miembro, junto con su rol — pueden crear proyectos owner y admin.

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

La selección por nombre es intencional: la cuenta de servicio ve todas las organizaciones de su propietario, ordenadas por nombre, y cada organización nueva desplaza las posiciones.

payment_method indica cómo paga la organización sus facturas: sepa_debit mientras esté activo un mandato de adeudo directo SEPA, transfer en caso contrario. Donde su rol es solo member, el campo no aparece: ese rol tampoco ve datos de pago en el portal. GET /organizations/{orgId} devuelve una organización con su mandato, con el IBAN enmascarado.

3. Crear el proyecto​

Los campos obligatorios son name (100 caracteres como máximo) y availability_zone_id. Son opcionales alert_email, billing_reference, anomaly_detection (por defecto false), immutable_storage (por defecto false) y — solo con almacenamiento inmutable — retention_days (de 1 a 365, por defecto 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\"}"

Respuesta con estado 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. Crear un token de copia de seguridad​

Un token de copia de seguridad pertenece exactamente a un proyecto. Con type = write el cliente hace copias; con type = read restaura. Sin indicación se crea un token de escritura para Linux; operating_system admite Linux, Windows y macOS. Opcionalmente, usage_count_limit, rate_limit_per_minute y rate_limit_per_hour limitan el uso.

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

Respuesta con estado 201:

{
"token": {
"id": "c4d1e8f2-6a3b-4c9d-8e7f-1a2b3c4d5e6f",
"type": "write",
"secret": "9f3e7b1c…a41c",
"zone_ready": false
}
}
El secreto solo aparece en esta respuesta

secret es el token de copia de seguridad propiamente dicho (128 caracteres hexadecimales). Se entrega una sola vez y no puede consultarse después — la plataforma solo guarda un hash. Deposítelo de inmediato en su gestor de secretos.

La zona de almacenamiento solo conoce un token nuevo una vez que lo ha asumido, normalmente en menos de un segundo; hasta entonces lo rechaza. zone_ready muestra el estado: false significa aún no asumido, true asumido. Si quiere hacer una copia justo después de crearlo, consulte la lista de tokens (paso 5) hasta que el token indique true. Con null la zona no confirma tokens y no hay nada que esperar. El proveedor de Terraform espera por sí mismo a partir de la versión 0.1.5.

Un token de lectura para restauraciones se crea de la misma manera:

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. Listar los tokens​

La lista contiene solo metadatos — nunca un secreto. Los tokens revocados ya no aparecen.

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. Revocar un 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. Cerrar el proyecto​

Un proyecto no se borra, sino que se cierra: el estado pasa a closing, todos los tokens de escritura se revocan de inmediato y la respuesta indica cuántos. La llamada es idempotente — un proyecto ya cerrado responde de nuevo con 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
}

Miembros y permisos​

Lo que hace en el portal en la página Permisos también puede hacerlo a través de la API, con las mismas reglas: invitar y quitar miembros, cambiar su rol en la organización, crear grupos de permisos y añadirles miembros. La API identifica a una persona por su identificador numérico (id), que aparece en la lista de miembros.

Cada cambio figura en el registro de auditoría de la organización, marcado con "via": "api". Un cambio en un grupo que pertenece a un proyecto aparece además en el registro de auditoría de ese proyecto.

Listar los miembros​

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 es el rol en la organización. Todo rol salvo member se aplica a todos los proyectos de la organización; member no concede nada por sí solo, y los derechos provienen entonces de los grupos de permisos.

Invitar a un miembro y cambiar su rol​

Solo se puede invitar a quien ya tenga una cuenta de lionbackup. La persona se incorpora como 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"}'

Solo un owner cambia un rol en la organización:

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} quita a una persona por completo de la organización, de todos sus roles y grupos en ella. Una organización conserva su último owner, y ningún proyecto pierde su último owner (409).

Crear un grupo de permisos y añadir miembros​

Un grupo otorga a sus miembros un rol (level) en el proyecto al que está vinculado. La vinculación se hace al crearlo, mediante 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\":\"Equipo de restauración\",\"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 }

Si repite la llamada, la respuesta es "added": false y no cambia nada. Con PATCH cambia el nombre y el nivel de un grupo; con DELETE quita un miembro (…/members/{id}) o el propio grupo vacío. GET /organizations/{orgId}/permission-groups lista los grupos con sus proyectos y miembros.

Un grupo sin project_id no está vinculado a ningún proyecto y, por tanto, no otorga ningún rol de proyecto. lionbackup crea por sí mismo el grupo owner de cada proyecto; no se puede renombrar, degradar ni eliminar (409 owner_group), y su último miembro permanece (409 last_owner). Para traspasar la propiedad, añada primero al nuevo owner.

Lo que debe saber​

Permisos por acción​

La API comprueba los mismos roles que el portal:

AcciónRol
Leer la organización (forma de pago, mandato enmascarado)cualquier rol en la organización salvo member
Leer el proyecto, listar los tokenscualquier rol en el proyecto
Modificar el proyecto, crear tokensowner, admin, writer
Revocar tokensowner, admin
Crear el proyecto, cerrar el proyectoowner o admin de la organización
Invitar y quitar miembrosowner o admin de la organización
Cambiar un rol en la organizaciónowner de la organización
Listar miembros y grupos, modificar gruposowner o admin de la organización; owner de un proyecto para sus grupos

404 en lugar de 403​

Un recurso que no existe y uno sobre el que usted no tiene ningún rol responden igual: 404 con {"error":"not_found"}. Así la API no revela qué identificadores existen. Un 403 con permission_denied solo lo recibe cuando puede ver el recurso pero no realizar la acción.

La publicación en la zona es asíncrona​

Un token nuevo se transmite a la Storage Zone después de crearlo. Hasta que eso ocurra, la zona rechaza el token con 401 — normalmente cuestión de segundos, en caso de avería hasta la siguiente sincronización. No vuelva a crear el token entonces; inténtelo de nuevo más tarde. A la inversa, un token revocado puede seguir siendo válido brevemente en la zona.

Cierre de un proyecto​

Cerrar revoca de inmediato todos los tokens de escritura y pone el proyecto en closing. Los tokens de lectura siguen siendo válidos durante el período de retención y, mientras quede una copia dentro de su retención, también puede crear tokens de lectura nuevos para seguir restaurando las copias guardadas. Un proyecto en closing rechaza tokens de escritura nuevos (409 project_closed); cuando está closed ya no acepta ningún token. Del mismo modo, una organización cerrada rechaza proyectos nuevos (409 organization_closed).

Detección de anomalías​

Con "anomaly_detection": true activa la detección de anomalías de un proyecto, al crearlo o más tarde; es el mismo ajuste que en la configuración del proyecto en el portal. Aprende el ritmo del proyecto con las tres primeras copias de seguridad y después informa de tamaños, duraciones y números de archivos inusuales, copias ausentes o adicionales y archivos sin cifrar mediante mensajes en el portal.

curl -s -X PATCH "$API/projects/$PROJECT_ID" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"anomaly_detection":true}'

El valor debe ser un booleano JSON; la API responde a "true", 1 o null con 400 invalid_request. El campo anomaly_phase indica en qué punto está la detección: learning, monitored, paused (mientras el proyecto se cierra o la organización está bloqueada), ended u off. La detección se pone al día en unos cinco minutos: hasta que registra el proyecto, anomaly_phase es null, y tras un cambio el campo muestra mientras tanto el estado anterior.

Límites de frecuencia​

LímiteValorSe aplica a
Peticiones por dirección IP60/minutocada petición a la API
Peticiones por cuenta de servicio60/minutocada petición autenticada
Tamaño de una petición1 MBel contenido enviado

Cada respuesta autenticada lleva X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset (hora Unix en la que termina la ventana de un minuto en curso). Por encima del límite la API responde 429, {"error":"rate_limited"} y la cabecera Retry-After — espere esos segundos y repita la petición. El proveedor de Terraform lo hace por sí mismo.

Las cabeceras X-RateLimit-* pueden faltar: si falla la caché de contadores de la plataforma, la API deja temporalmente de contar por cuenta de servicio y tampoco anuncia entonces ningún presupuesto. En su automatización confíe en el estado 429 y en Retry-After, no en las cabeceras.

Formato de los errores​

Cada error es un objeto JSON con exactamente un campo: {"error":"<code>"}. El código es estable y está pensado para programas; ramifique según él, no solo según el estado HTTP.

EstadoCódigoSignificado
400invalid_requestel contenido no es JSON, falta un campo obligatorio o un valor no es válido
400invalid_zoneavailability_zone_id es desconocido o la zona no está active
400retention_out_of_rangeretention_days está fuera del rango de 1 a 365
401invalid_tokenel token de acceso falta, no es válido o ha caducado, o la cuenta de servicio se borró
403owner_inactivela persona a la que pertenece la cuenta de servicio está desactivada
403permission_deniedsu rol no permite esta acción
404not_foundrecurso desconocido o no visible para usted
405method_not_allowedla ruta existe, el método HTTP no
409organization_closedla organización se está cerrando o está cerrada
409project_closedel proyecto está closed, o closing y se pidió un token de escritura
409already_memberla persona ya pertenece a la organización
409not_org_membersolo los miembros de la organización entran en sus grupos — invítela primero
409last_ownerla organización o un grupo owner perdería su último owner
409project_last_ownerun proyecto perdería su último owner
409owner_groupel grupo owner de un proyecto se queda como está
409group_not_emptysolo se puede eliminar un grupo vacío
422user_not_registeredno existe ninguna cuenta de lionbackup para esta dirección
429rate_limitedlímite de frecuencia — respete Retry-After
500internal_errorerror inesperado en la plataforma
502identity_provider_errorla gestión de usuarios no aplicó el cambio, o solo en parte — lea el estado actual y vuelva a intentarlo
503service_unavailabletemporalmente no disponible — inténtelo de nuevo más tarde

Terraform​

Para Terraform y OpenTofu existe un proveedor que usa la misma API y gestiona proyectos, tokens de copia de seguridad, miembros y grupos de permisos como recursos. Dónde obtenerlo, cómo configurarlo y un ejemplo completo se encuentran en la página Terraform.

Referencia​

La especificación completa está disponible para descargar como documento OpenAPI 3.1: openapi.yaml. La propia API sirve el mismo archivo en /api/v1/openapi.yaml — describe por tanto siempre exactamente la versión en ejecución.

Loading the API reference…