Aller au contenu

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.

  1. Ouvrez Paramètres › API d'administration dans la console.
  2. Saisissez un nom pour le jeton, de 1 à 100 caractères.
  3. Cochez les portées dont le jeton a besoin.
  4. Choisissez sa durée de vie : de 1 à 365 jours, 90 par défaut. La console propose 30, 90, 180 et 365.
  5. 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és sluis- 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.

  • read autorise les requêtes GET sur la famille.
  • write autorise toutes les méthodes sur la famille et inclut read.
  • Les familles en lecture seule (usage, policy, audit et billing) 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.
FamilleLecture (GET)Écriture
usage
Consommation par organisation (export de facturation)
GET /admin/v1/usage
GET /admin/usage
Pas de portée en écriture
orgs
Organisations 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
members
Membres, 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
keys
Clé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}
policy
La politique par défaut active (lecture seule)
GET /admin/policy
Pas de portée en écriture
audit
Journal 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
billing
Solde, 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
scim
Provisionnement 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"
fromYYYY-MM-DD (UTC), inclus. Indiquez from et to ensemble, ou aucun des deux.
toYYYY-MM-DD (UTC), exclu, après from. 92 jours au plus. Sans from ni to, vous obtenez le mois civil précédent.
kindagency (la racine elle-même), client (une organisation sous elle) ou standalone (une racine sans clients).
list_centsPrix catalogue du fournisseur, en centimes. 0 pour vos propres clés de fournisseur (BYOK).
billable_centsCentimes 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 403 sinon.
  • 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 }' …

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ée audit:read), ou dans la console sous Journal d'audit.
  • audit:read ne 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.

StatutSignification
400Corps ou requête invalide. Le message nomme le champ.
401Jeton absent, invalide, révoqué ou expiré.
402La facturation n'est pas active, par exemple pour créer une organisation cliente.
403Les 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.
429Limite 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.