API de administración
Administre 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 › API de administración en la consola
Crear un token
Cree un token en la consola y envíelo como bearer token en cada solicitud de la API de administración. Necesita el rol de propietario o administrador y una dirección de correo verificada.
- Abra Ajustes › API de administración en la consola.
- Escriba un nombre para el token, de 1 a 100 caracteres.
- Marque los permisos que necesita el token.
- Elija su vigencia: de 1 a 365 días, 90 por defecto. La consola ofrece 30, 90, 180 y 365.
- Cree el token y copie el secreto de inmediato. Solo se muestra una vez.
Guarde el secreto en el almacén de secretos de su integración, nunca en el código. Sluis solo conserva sus 16 primeros caracteres, para que pueda reconocer el token en la lista.
Quién puede crear tokens
- Solo un propietario puede conceder un permiso de escritura, porque un token de escritura actúa como propietario en la API. Un administrador puede crear tokens de solo lectura.
- Solo una sesión de consola iniciada puede crear, listar o revocar tokens. Un token nunca puede hacerlo.
- Todo token caduca. No existe la opción de un token sin caducidad.
- El secreto empieza por
sluis_admin_. Las clavessluis-que sus aplicaciones usan para llamar a los modelos no funcionan aquí.
# 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íe el secreto como bearer token en cada solicitud: Authorization: Bearer $SLUIS_ADMIN_TOKEN.
Un token pertenece a la organización en la que se creó. Solo llega a los endpoints que sus permisos autorizan, y todos los demás responden 403.
Cómo funcionan los permisos
Un permiso combina una familia y un nivel de acceso, por ejemplo usage:read u orgs:write.
readautoriza solicitudesGETsobre la familia.writeautoriza todos los métodos sobre la familia e incluyeread.- Las familias de solo lectura (
usage,policy,auditybilling) no tienen permiso de escritura. - Los permisos se fijan al crear el token. Para cambiarlos, cree un token nuevo.
| Familia | Lectura (GET) | Escritura |
|---|---|---|
usageConsumo por organización (exportación de facturación) | GET /admin/v1/usage GET /admin/usage | Sin permiso de escritura |
orgsOrganizaciones y sus clientes, presupuestos y márgenes | GET /admin/orgs | POST /admin/orgs PUT /admin/orgs/{id}/name PUT /admin/orgs/{id}/budget PUT /admin/orgs/{id}/margin |
membersMiembros, roles e invitaciones (invitación solo por correo) | GET /admin/members | POST /admin/members PUT/DELETE /admin/members/{id} POST /admin/members/{id}/invite |
keysClaves API y workloads | GET /admin/keys GET /admin/workloads* | POST /admin/keys PUT/DELETE /admin/keys/{id} POST /admin/keys/{id}/rotate POST /admin/keys/{id}/move POST /admin/workloads PATCH/DELETE /admin/workloads/{id} PUT/DELETE /admin/workloads/{id}/members/{user} |
policyLa política predeterminada activa (solo lectura) | GET /admin/policy | Sin permiso de escritura |
auditRegistro de auditoría y auditoría de operadores (metadatos, sin contenido) | GET /admin/audit /admin/operator-audit /admin/requests/live | Sin permiso de escritura |
billingSaldo, facturas y extractos (solo lectura, nunca un pago) | GET /admin/billing /admin/billing/invoice/{id} /admin/billing/statement/{y}/{m} /admin/usage/org-spend | Sin permiso de escritura |
scimAprovisionamiento SCIM de personas y grupos desde su proveedor de identidad | GET /scim/v2/* | POST/PUT/PATCH/DELETE /scim/v2/Users* /scim/v2/Groups* |
# a token without the scope for this endpoint { "error": { "message": "token scope does not allow this endpoint", "type": "sluis_error" } }
Solo en la consola
Estas acciones se quedan en la consola sea cual sea el permiso del token, así que un script nunca puede ejecutarlas:
- Gestionar tokens.
- Ajustes de doble factor.
- Credenciales de proveedor (sus propias claves de proveedor).
- Acuerdos legales.
- Cambiar de organización y crear una organización independiente.
- Cambiar la política y su historial de versiones.
- Trazas de solicitudes, que contienen contenido descifrado.
- Cualquier acción de pago de la facturación.
Cualquier endpoint que no esté en la tabla anterior está cerrado a los tokens del mismo modo.
Exportación de consumo para facturación
GET /admin/v1/usage devuelve el consumo de todo su árbol de organizaciones en un intervalo de fechas, para facturar a cada cliente. Requiere el permiso usage:read.
- Una entrada por organización: la raíz y cada cliente, incluidos los clientes sin consumo, para que una ronda de facturación vea a todos.
- Cada organización tiene líneas por proveedor y modelo.
- Los importes son céntimos enteros en euros, sin IVA.
- Las cifras salen de la misma consulta que la página de facturación de la consola, así que la exportación coincide con su extracto mensual.
- Solo una organización raíz puede llamarlo. 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
}| from | YYYY-MM-DD (UTC), incluido. Indique from y to juntos, o ninguno de los dos. |
| to | YYYY-MM-DD (UTC), excluido, posterior a from. Como máximo 92 días. Sin from ni to se obtiene el mes natural anterior. |
| kind | agency (la propia raíz), client (una organización bajo ella) o standalone (una raíz sin clientes). |
| list_cents | Precio de lista del proveedor, en céntimos. 0 con claves de proveedor propias (BYOK). |
| billable_cents | Céntimos sin IVA: lo que se cobra a la raíz por esa organización. total_billable_cents es su suma. |
Para sus facturas
Una entrada de organisations es una factura de cliente, y cada fila de lines es una línea de factura. billable_cents va sin IVA: deje que su herramienta contable (Moneybird, por ejemplo) añada el tipo impositivo.
Guarde period.from y period.to en la factura. Así, repetir el mismo mes es idempotente por su parte.
Dar de alta organizaciones, miembros y claves
Use los permisos de escritura para crear y mantener clientes desde su propio CRM o proveedor de identidad. Cada cambio sigue las mismas reglas de validación, de rol y de facturación que la consola.
Organizaciones cliente
Con orgs:write crea organizaciones cliente bajo su agencia y fija su nombre, presupuesto y margen.
- El propietario que creó el token pasa a ser el primer propietario de cada cliente nuevo. Cuando un token crea o renombra una organización, Sluis comprueba que esa persona siga siendo propietaria y responde
403si no. - Crear una organización cliente exige facturación activa, porque los clientes se facturan a su cuenta.
- Un administrador de agencia que crea un cliente en la consola no pasa a ser su propietario. Solo conserva el acceso de administrador que hereda de la agencia.
Personas
Con members:write, un token invita a personas por correo, cambia roles y retira personas.
- La persona invitada recibe un correo de activación y elige su propia contraseña. Un token no puede establecer una contraseña.
- Si la dirección ya tiene una cuenta de Sluis, esa persona recibe en su lugar una invitación para unirse y es miembro solo después de aceptarla. La respuesta indica
pending_acceptance: true. - Como máximo 60 invitaciones por hora y organización. Por encima, la respuesta es
429.
Claves API y workloads
Con keys:write crea un workload y, dentro de él, una clave. El secreto de la clave se devuelve una sola vez, en la respuesta que la crea.
SCIM
Con scim:write, su proveedor de identidad aprovisiona personas y grupos mediante SCIM 2.0 en /scim/v2. Un token SCIM no llega a nada bajo /admin, y ningún otro token llega a /scim/v2.
# 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" }'
Lo que un token no puede hacer
- Conceder el rol de propietario o cambiar el rol de un propietario.
- Retirar a un propietario.
- Establecer una contraseña.
- Leer el contenido de solicitudes o respuestas.
El mismo límite vale para las personas: solo un propietario con sesión iniciada puede conceder el rol de propietario, o cambiar o retirar a un propietario. Un administrador recibe 403.
Caducidad, límite de tasa, revocación y auditoría
Caducidad y revocación
- Todo token caduca. Un token caducado responde
401, igual que uno revocado, y la consola lo muestra como caducado. - Para revocar un token, use la misma tabla en la consola. Deja de funcionar en menos de 30 segundos.
- Un token se revoca automáticamente cuando la persona que lo creó es retirada, pierde el rol de propietario o cambia su contraseña.
Límite de tasa
Cada token puede hacer 600 solicitudes por minuto. Por encima, el gateway responde 429 con una cabecera Retry-After: espere esos segundos y reintente.
Las solicitudes rechazadas por falta de permiso también cuentan para el límite.
Auditoría
- Cada cambio hecho con un token se registra en la auditoría de operadores, con el id y el nombre del token como actor. El rastro siempre nombra la integración que actuó.
- Léala con
GET /admin/operator-audit(permisoaudit:read) o en la consola, en Registro de auditoría. audit:readdevuelve solo metadatos, nunca el contenido de solicitudes o respuestas.
# 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 formato que el resto de la API: un objeto error con un message y un type. El código de estado indica qué hacer.
| Estado | Significado |
|---|---|
400 | Cuerpo o consulta inválidos. El mensaje nombra el campo. |
401 | Token ausente, inválido, revocado o caducado. |
402 | La facturación no está activa, por ejemplo al crear una organización cliente. |
403 | Los permisos del token no cubren este endpoint, o las reglas de rol rechazan la acción, por ejemplo conceder el rol de propietario. |
429 | Límite de tasa por token superado, o demasiadas invitaciones. Espere Retry-After segundos. |
Un 403 con token scope does not allow this endpoint significa que el token es válido pero no tiene el permiso. Cree un token nuevo con el permiso correcto en lugar de ampliar uno existente.