API de administración

Administra una organización sin sesión de navegador: tokens con permisos acotados y caducidad para exportaciones de facturación, alta de clientes y miembros, y feeds de auditoría.

Abrir Ajustes › Admin API en la consola

Crear un token

Abre Ajustes › Admin API en la consola (propietario o admin, con dirección de correo verificada). Da un nombre al token, marca los permisos que necesita y elige su vigencia: hasta 365 días, 90 por defecto (la consola ofrece 30/90/180/365). El secreto se muestra una sola vez; solo se conservan sus primeros caracteres para reconocerlo. Guárdalo en el almacén de secretos de tu integración, nunca en el código.

Los permisos de escritura solo puede concederlos un propietario de la organización, porque un token de escritura actúa como propietario en la API. Los tokens se crean solo desde una sesión iniciada: un token nunca puede crear, listar ni revocar tokens.

# the token is shown once, at creation: keep it in your integration's secret store
export SLUIS_ADMIN_TOKEN="sluis_admin_…"

curl https://api.sluis.ai/admin/orgs \
  -H "Authorization: Bearer $SLUIS_ADMIN_TOKEN"

Autenticación y permisos

Envía el secreto como bearer token en cada petición. Un token está ligado a la organización en la que se creó y solo alcanza los endpoints que permiten sus permisos; todo lo demás responde 403. Los permisos se agrupan por familia: read abre GET en la familia, write abre todos los métodos e implica read. Las familias de solo lectura no tienen permiso write.

Solo con sesión, lleve lo que lleve el token: gestión de tokens, ajustes del segundo factor, credenciales de proveedores y gateways, acuerdos legales, cambio de organización, historial de versiones de la política y cualquier acción de pago.

# a token without the scope for this endpoint
{
  "error": {
    "message": "token scope does not allow this endpoint",
    "type": "sluis_error"
  }
}

Exportación de consumo para facturación

GET /admin/v1/usage devuelve el consumo de tu árbol de organizaciones en una ventana, una entrada por organización — incluidos los clientes sin consumo, para que una ejecución de facturación vea a todos. Los importes son céntimos enteros sin IVA, calculados con la misma consulta que la página de facturación de la consola, así que la exportación cuadra con tu extracto mensual.

from y to son fechas YYYY-MM-DD en UTC, intervalo semiabierto [from, to), como máximo 92 días; si se omiten cubren el mes natural anterior. Cada organización lleva líneas por proveedor y modelo. Guarda el periodo en tu factura para que repetir el mismo mes sea idempotente en tu lado. Solo organizaciones raíz: el token de una organización cliente recibe 403.

# usage:read — every organisation under the root, per provider/model, for one month
curl "https://api.sluis.ai/admin/v1/usage?from=2026-08-01&to=2026-09-01" \
  -H "Authorization: Bearer $SLUIS_ADMIN_TOKEN"

{
  "period": { "from": "2026-08-01", "to": "2026-09-01" },
  "currency": "EUR",
  "root": { "id": "…", "name": "Agency BV" },
  "organisations": [{
    "id": "…", "name": "Client BV", "kind": "client", "parent_id": "…",
    "requests": 123,
    "tokens": { "input": 1, "output": 2, "total": 3 },
    "list_cents": 1000, "billable_cents": 1200,
    "lines": [{ "provider": "openai", "model": "gpt-5", "requests": 10,
                "input_tokens": 1, "output_tokens": 2, "list_cents": 500, "billable_cents": 600 }]
  }],
  "total_billable_cents": 1200
}

Dar de alta organizaciones, miembros y claves

Con orgs:write una agencia crea organizaciones cliente y fija su presupuesto y margen desde su propio CRM; el propietario que creó el token pasa a ser el primer propietario de cada cliente nuevo, así que debe seguir siendo propietario. members:write invita solo por correo, cambia roles y elimina personas — un token no puede conceder el rol de propietario, establecer una contraseña ni eliminar a un propietario. keys:write da de alta claves API y cargas de trabajo.

Cada mutación pasa las mismas validaciones, reglas de rol y de facturación que la consola: crear organizaciones cliente sigue exigiendo facturación activa. Un token no puede conceder el rol de propietario, establecer contraseñas ni leer el contenido de peticiones y respuestas.

# orgs:write — a new client organisation under your agency (201 → { id, name, kind, parent_id, … })
curl https://api.sluis.ai/admin/orgs \
  -H "Authorization: Bearer $SLUIS_ADMIN_TOKEN" -H "Content-Type: application/json" \
  -d '{ "name": "Client BV", "allocated_budget_microeur": 250000000 }'

# its monthly budget (micro-euros; null clears) and reseller margin (basis points)
curl -X PUT https://api.sluis.ai/admin/orgs/$ORG_ID/budget  -d '{ "allocated_budget_microeur": 500000000 }' …
curl -X PUT https://api.sluis.ai/admin/orgs/$ORG_ID/margin  -d '{ "margin_bps": 2000 }' …

# members:write — invite (201; an activation mail goes out), change a role, remove
# a token invites by email only: it cannot set a password or grant the owner role
curl https://api.sluis.ai/admin/members \
  -H "Authorization: Bearer $SLUIS_ADMIN_TOKEN" -H "Content-Type: application/json" \
  -d '{ "email": "j.devries@client.nl", "role": "member" }'

curl -X PUT    https://api.sluis.ai/admin/members/$USER_ID -d '{ "role": "admin" }' …
curl -X DELETE https://api.sluis.ai/admin/members/$USER_ID …

# keys:write — a workload, then a key inside it (the secret is returned once)
curl https://api.sluis.ai/admin/workloads -d '{ "name": "crm-bot" }' …
curl https://api.sluis.ai/admin/keys \
  -H "Authorization: Bearer $SLUIS_ADMIN_TOKEN" -H "Content-Type: application/json" \
  -d '{ "name": "prod", "workload_id": "…", "environment": "production" }'

Caducidad, límite de tasa, revocación y auditoría

Todo token creado en la consola caduca; un token caducado responde 401 igual que uno revocado, y la consola lo lista como caducado. Revócalo desde la misma tabla — deja de autenticar en menos de 30 segundos. Cada token está limitado a 600 peticiones por minuto; por encima, el gateway responde 429 con una cabecera Retry-After: espera y reintenta.

Cada mutación hecha con un token se registra en la auditoría de operadores (GET /admin/operator-audit, también en la consola bajo Registro de auditoría) con el id y el nombre del token como actor, de modo que el rastro siempre nombra la integración que actuó. audit:read devuelve solo metadatos — nunca el contenido de peticiones o respuestas. Los tokens se revocan automáticamente cuando el usuario que los creó es eliminado, pierde el rol de propietario o cambia su contraseña.

# audit:read — a mutation made with a token names the token as its actor
curl https://api.sluis.ai/admin/operator-audit -H "Authorization: Bearer $SLUIS_ADMIN_TOKEN"
{
  "rows": [{
    "action": "org.create", "target_type": "organisation", "target_id": "…",
    "actor_email": "admin-token",
    "metadata": { "name": "Client BV", "actor_token": { "id": "…", "name": "crm-sync" } }
  }]
}

Errores

Los errores usan el mismo envoltorio que el resto de la API: un objeto error con message y type. El código de estado indica qué hacer.

Un 403 con "token scope does not allow this endpoint" significa que el token existe y es válido pero le falta el permiso: crea un token nuevo con el permiso correcto en vez de ampliar uno existente — los permisos se fijan al crearlo.