API d'administration
Administrez une organisation sans session navigateur : jetons à portées limitées et à expiration pour les exports de facturation, le provisionnement de clients et de membres, et les flux d'audit.
Ouvrir Paramètres › API d'administration dans la console
Créer un jeton
Créez un jeton dans la console, puis envoyez-le comme bearer token avec chaque requête de l'API d'administration. Il faut le rôle de propriétaire ou d'administrateur et une adresse e-mail vérifiée.
- Ouvrez Paramètres › API d'administration dans la console.
- Saisissez un nom pour le jeton, de 1 à 100 caractères.
- Cochez les portées dont le jeton a besoin.
- Choisissez sa durée de vie : de 1 à 365 jours, 90 par défaut. La console propose 30, 90, 180 et 365.
- Créez le jeton et copiez tout de suite le secret. Il n'est affiché qu'une seule fois.
Rangez le secret dans le coffre de secrets de votre intégration, jamais dans le code. Sluis n'en garde que les 16 premiers caractères, pour vous permettre de reconnaître le jeton dans la liste.
Qui peut créer des jetons
- Seul un propriétaire peut accorder une portée en écriture, car un jeton en écriture agit comme propriétaire sur l'API. Un administrateur peut créer des jetons en lecture seule.
- Seule une session de console connectée peut créer, lister ou révoquer des jetons. Un jeton ne le peut jamais.
- Tout jeton expire. Il n'existe pas d'option pour un jeton sans expiration.
- Le secret commence par
sluis_admin_. Les cléssluis-que vos applications utilisent pour appeler les modèles ne fonctionnent pas ici.
# 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"
Authentification et portées
Envoyez le secret comme bearer token à chaque requête : Authorization: Bearer $SLUIS_ADMIN_TOKEN.
Un jeton appartient à l'organisation dans laquelle il a été créé. Il n'atteint que les endpoints autorisés par ses portées, et tous les autres répondent 403.
Comment fonctionnent les portées
Une portée associe une famille et un niveau d'accès, par exemple usage:read ou orgs:write.
readautorise les requêtesGETsur la famille.writeautorise toutes les méthodes sur la famille et inclutread.- Les familles en lecture seule (
usage,policy,auditetbilling) n'ont pas de portée en écriture. - Les portées sont fixées à la création. Pour les changer, créez un nouveau jeton.
| Famille | Lecture (GET) | Écriture |
|---|---|---|
usageConsommation par organisation (export de facturation) | GET /admin/v1/usage GET /admin/usage | Pas de portée en écriture |
orgsOrganisations et leurs clients, budgets et marges | GET /admin/orgs | POST /admin/orgs PUT /admin/orgs/{id}/name PUT /admin/orgs/{id}/budget PUT /admin/orgs/{id}/margin |
membersMembres, rôles et invitations (invitation par e-mail uniquement) | GET /admin/members | POST /admin/members PUT/DELETE /admin/members/{id} POST /admin/members/{id}/invite |
keysClés API et 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 politique par défaut active (lecture seule) | GET /admin/policy | Pas de portée en écriture |
auditJournal d'audit et audit opérateur (métadonnées, sans contenu) | GET /admin/audit /admin/operator-audit /admin/requests/live | Pas de portée en écriture |
billingSolde, factures et relevés (lecture seule, jamais de paiement) | GET /admin/billing /admin/billing/invoice/{id} /admin/billing/statement/{y}/{m} /admin/usage/org-spend | Pas de portée en écriture |
scimProvisionnement SCIM des personnes et des groupes depuis votre fournisseur d'identité | 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" } }
Réservé à la console
Ces actions restent dans la console quelles que soient les portées d'un jeton, si bien qu'un script ne peut jamais les exécuter :
- La gestion des jetons.
- Les réglages du second facteur.
- Les identifiants de fournisseurs (vos propres clés de fournisseurs).
- Les accords juridiques.
- Le changement d'organisation et la création d'une organisation indépendante.
- La modification de la politique et son historique de versions.
- Les traces de requêtes, qui contiennent des contenus déchiffrés.
- Toute action de paiement de la facturation.
Tout endpoint absent du tableau ci-dessus est fermé aux jetons de la même façon.
Export de consommation pour la facturation
GET /admin/v1/usage renvoie la consommation de tout votre arbre d'organisations sur une période, pour facturer chaque client. Il faut la portée usage:read.
- Une entrée par organisation : la racine elle-même et chaque client, y compris les clients sans consommation, pour qu'un cycle de facturation voie tous les clients.
- Chaque organisation comporte des lignes par fournisseur et par modèle.
- Les montants sont des centimes entiers en euros, hors TVA.
- Les chiffres viennent de la même requête que la page Facturation de la console : l'export correspond donc à votre relevé mensuel.
- Seule une organisation racine peut l'appeler. Le jeton d'une organisation cliente reçoit
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), inclus. Indiquez from et to ensemble, ou aucun des deux. |
| to | YYYY-MM-DD (UTC), exclu, après from. 92 jours au plus. Sans from ni to, vous obtenez le mois civil précédent. |
| kind | agency (la racine elle-même), client (une organisation sous elle) ou standalone (une racine sans clients). |
| list_cents | Prix catalogue du fournisseur, en centimes. 0 pour vos propres clés de fournisseur (BYOK). |
| billable_cents | Centimes hors TVA : ce que la racine paie pour cette organisation. total_billable_cents en est la somme. |
Pour vos factures
Une entrée de organisations correspond à une facture client, et chaque ligne de lines à une ligne de facture. billable_cents est hors TVA : laissez votre outil comptable (Moneybird, par exemple) ajouter le taux de taxe.
Enregistrez period.from et period.to sur la facture. Ainsi, relancer le même mois est idempotent de votre côté.
Provisionner organisations, membres et clés
Utilisez les portées en écriture pour créer et tenir à jour vos clients depuis votre CRM ou votre fournisseur d'identité. Chaque modification suit les mêmes règles de validation, de rôle et de facturation que la console.
Organisations clientes
Avec orgs:write, vous créez des organisations clientes sous votre agence et fixez leur nom, leur budget et leur marge.
- Le propriétaire qui a créé le jeton devient le premier propriétaire de chaque nouveau client. Quand un jeton crée ou renomme une organisation, Sluis vérifie que cette personne est toujours propriétaire, et répond
403sinon. - Créer une organisation cliente exige une facturation active, car les clients sont facturés sur votre compte.
- Un administrateur d'agence qui crée un client dans la console n'en devient pas propriétaire. Il n'y garde que l'accès administrateur hérité de l'agence.
Personnes
Avec members:write, un jeton invite des personnes par e-mail, change les rôles et retire des personnes.
- Une personne invitée reçoit un e-mail d'activation et choisit son propre mot de passe. Un jeton ne peut pas définir de mot de passe.
- Si l'adresse a déjà un compte Sluis, la personne reçoit à la place une invitation à rejoindre l'organisation et n'en devient membre qu'après l'avoir acceptée. La réponse indique
pending_acceptance: true. - 60 invitations par heure et par organisation au maximum. Au-delà, la réponse est
429.
Clés API et workloads
Avec keys:write, vous créez un workload, puis une clé dedans. Le secret de la clé n'est renvoyé qu'une fois, dans la réponse qui la crée.
SCIM
Avec scim:write, votre fournisseur d'identité provisionne personnes et groupes via SCIM 2.0 sur /scim/v2. Un jeton SCIM n'atteint rien sous /admin, et aucun autre jeton n'atteint /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" }'
Ce qu'un jeton ne peut pas faire
- Accorder le rôle de propriétaire, ou changer le rôle d'un propriétaire.
- Retirer un propriétaire.
- Définir un mot de passe.
- Lire le contenu des requêtes ou des réponses.
La même limite vaut pour les personnes : seul un propriétaire connecté peut accorder le rôle de propriétaire, ou modifier ou retirer un propriétaire. Un administrateur reçoit 403.
Expiration, limite de débit, révocation et audit
Expiration et révocation
- Tout jeton expire. Un jeton expiré répond
401, comme un jeton révoqué, et la console l'affiche comme expiré. - Pour révoquer un jeton, utilisez la même table dans la console. Il cesse de fonctionner sous 30 secondes.
- Un jeton est révoqué automatiquement quand la personne qui l'a créé est retirée, perd le rôle de propriétaire ou change son mot de passe.
Limite de débit
Chaque jeton peut faire 600 requêtes par minute. Au-delà, la passerelle répond 429 avec un en-tête Retry-After : attendez ce nombre de secondes, puis réessayez.
Les requêtes refusées faute de portée comptent aussi dans la limite.
Audit
- Chaque modification faite avec un jeton est inscrite dans l'audit opérateur, avec l'identifiant et le nom du jeton comme acteur. La trace nomme toujours l'intégration qui a agi.
- Lisez-la avec
GET /admin/operator-audit(portéeaudit:read), ou dans la console sous Journal d'audit. audit:readne renvoie que des métadonnées, jamais le contenu des requêtes ou des réponses.
# 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" } } }] }
Erreurs
Les erreurs utilisent la même enveloppe que le reste de l'API : un objet error avec un message et un type. Le code de statut indique quoi faire.
| Statut | Signification |
|---|---|
400 | Corps ou requête invalide. Le message nomme le champ. |
401 | Jeton absent, invalide, révoqué ou expiré. |
402 | La facturation n'est pas active, par exemple pour créer une organisation cliente. |
403 | Les portées du jeton ne couvrent pas cet endpoint, ou les règles de rôle refusent l'action, par exemple accorder le rôle de propriétaire. |
429 | Limite de débit par jeton dépassée, ou trop d'invitations. Attendez Retry-After secondes. |
Un 403 avec token scope does not allow this endpoint signifie que le jeton est valide mais n'a pas la portée. Créez un nouveau jeton avec la bonne portée plutôt que d'élargir un jeton existant.