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 › Admin API dans la console

Créer un jeton

Ouvrez Paramètres › Admin API dans la console (propriétaire ou admin, avec une adresse e-mail vérifiée). Nommez le jeton, cochez les portées nécessaires et choisissez sa durée de vie : jusqu'à 365 jours, 90 par défaut (la console propose 30/90/180/365). Le secret n'est affiché qu'une seule fois ; seuls ses premiers caractères sont conservés pour le reconnaître. Rangez-le dans le coffre de secrets de votre intégration, jamais dans le code.

Les portées en écriture ne peuvent être accordées que par un propriétaire de l'organisation, car un jeton en écriture agit comme propriétaire sur l'API. Les jetons sont créés uniquement depuis une session connectée : un jeton ne peut jamais créer, lister ou révoquer des jetons.

# 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. Un jeton est lié à l'organisation dans laquelle il a été créé et n'atteint que les endpoints autorisés par ses portées ; tout le reste répond 403. Les portées sont groupées par famille : read ouvre GET sur la famille, write ouvre toutes les méthodes et implique read. Les familles en lecture seule n'ont pas de portée write.

Réservé à la session quel que soit le jeton : gestion des jetons, réglages du second facteur, identifiants fournisseurs et passerelles, accords juridiques, changement d'organisation, historique des versions de politique, et toute action de paiement.

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

Export de consommation pour la facturation

GET /admin/v1/usage renvoie la consommation de votre arbre d'organisations sur une fenêtre, une entrée par organisation — y compris les clients sans consommation, pour qu'un cycle de facturation voie chaque client. Les montants sont des centimes entiers hors TVA, calculés avec la même requête que la page Facturation de la console : l'export se rapproche de votre relevé mensuel.

from et to sont des dates YYYY-MM-DD en UTC, intervalle semi-ouvert [from, to), 92 jours au plus ; omis, ils couvrent le mois civil précédent. Chaque organisation porte des lignes par fournisseur et modèle. Enregistrez la période sur votre facture pour qu'une relance du même mois soit idempotente de votre côté. Organisations racines uniquement : 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
}

Provisionner organisations, membres et clés

Avec orgs:write, une agence crée des organisations clientes et fixe leur budget et leur marge depuis son propre CRM ; le propriétaire qui a créé le jeton devient le premier propriétaire de chaque nouveau client, il doit donc être encore propriétaire. members:write invite par e-mail uniquement, change les rôles et retire des personnes — un jeton ne peut ni accorder le rôle propriétaire, ni définir un mot de passe, ni retirer un propriétaire. keys:write provisionne clés API et charges de travail.

Chaque mutation suit les mêmes validations, règles de rôle et règles de facturation que la console : créer des organisations clientes exige toujours une facturation active. Un jeton ne peut pas accorder le rôle propriétaire, définir des mots de passe, ni lire le contenu des requêtes et des réponses.

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

Expiration, limite de débit, révocation et audit

Tout jeton créé dans la console expire ; un jeton expiré répond 401 exactement comme un jeton révoqué, et la console l'affiche comme expiré. Révoquez-le depuis la même table — il cesse d'authentifier sous 30 secondes. Chaque jeton est limité à 600 requêtes par minute ; au-delà, la passerelle répond 429 avec un en-tête Retry-After : patientez puis réessayez.

Chaque mutation effectuée avec un jeton est inscrite dans le journal d'audit opérateur (GET /admin/operator-audit, aussi dans la console sous Journal d'audit) avec l'identifiant et le nom du jeton comme acteur : la trace nomme toujours l'intégration qui a agi. audit:read ne renvoie que des métadonnées — jamais le contenu des requêtes ou des réponses. Les jetons sont révoqués automatiquement lorsque l'utilisateur qui les a créés est retiré, perd le rôle propriétaire ou change son mot de passe.

# 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.

Un 403 « token scope does not allow this endpoint » signifie que le jeton existe et 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 — les portées sont fixées à la création.