Admin-API
Eine Organisation ohne Browser-Sitzung verwalten: Tokens mit Scopes und Ablauf für Abrechnungsexporte, das Anlegen von Kunden und Mitgliedern sowie Audit-Feeds.
Einstellungen › Admin-API in der Konsole öffnen
Token erstellen
Erstellen Sie ein Token in der Konsole und senden Sie es bei jeder Anfrage an die Admin-API als Bearer-Token mit. Sie brauchen die Rolle Inhaber oder Admin und eine bestätigte E-Mail-Adresse.
- Öffnen Sie in der Konsole Einstellungen › Admin-API.
- Geben Sie dem Token einen Namen mit 1 bis 100 Zeichen.
- Wählen Sie die Scopes, die das Token braucht.
- Wählen Sie die Laufzeit: 1 bis 365 Tage, standardmäßig 90. Die Konsole bietet 30, 90, 180 und 365.
- Erstellen Sie das Token und kopieren Sie das Geheimnis sofort. Es wird nur ein einziges Mal angezeigt.
Legen Sie das Geheimnis im Secret-Store Ihrer Integration ab, nie im Quellcode. Sluis speichert nur die ersten 16 Zeichen, damit Sie das Token in der Liste wiedererkennen.
Wer Tokens erstellen darf
- Nur ein Inhaber kann einen Schreib-Scope vergeben, denn ein Schreib-Token handelt auf der API als Inhaber. Ein Admin kann Tokens mit reinem Lesezugriff erstellen.
- Nur eine angemeldete Konsolen-Sitzung kann Tokens erstellen, auflisten oder widerrufen. Ein Token kann das nie.
- Jedes Token läuft ab. Ein Token ohne Ablauf gibt es nicht.
- Das Geheimnis beginnt mit
sluis_admin_. Diesluis--Schlüssel, die Ihre Apps für Modellaufrufe nutzen, funktionieren hier nicht.
# 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"
Authentifizierung und Scopes
Senden Sie das Geheimnis bei jeder Anfrage als Bearer-Token: Authorization: Bearer $SLUIS_ADMIN_TOKEN.
Ein Token gehört zu der Organisation, in der es erstellt wurde. Es erreicht nur die Endpunkte, die seine Scopes erlauben, alle anderen antworten mit 403.
So funktionieren Scopes
Ein Scope besteht aus einer Familie und einer Zugriffsstufe, zum Beispiel usage:read oder orgs:write.
readerlaubtGET-Anfragen auf der Familie.writeerlaubt jede Methode auf der Familie und schließtreadein.- Familien nur zum Lesen (
usage,policy,auditundbilling) haben keinen Schreib-Scope. - Scopes stehen bei der Erstellung fest. Um sie zu ändern, erstellen Sie ein neues Token.
| Familie | Lesen (GET) | Schreiben |
|---|---|---|
usageVerbrauch pro Organisation (Abrechnungsexport) | GET /admin/v1/usage GET /admin/usage | Kein Schreib-Scope |
orgsOrganisationen und ihre Kunden, Budgets und Margen | GET /admin/orgs | POST /admin/orgs PUT /admin/orgs/{id}/name PUT /admin/orgs/{id}/budget PUT /admin/orgs/{id}/margin |
membersMitglieder, Rollen und Einladungen (Einladung nur per E-Mail) | GET /admin/members | POST /admin/members PUT/DELETE /admin/members/{id} POST /admin/members/{id}/invite |
keysAPI-Schlüssel und 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} |
policyDie aktive Standardrichtlinie (nur lesen) | GET /admin/policy | Kein Schreib-Scope |
auditAudit-Log und Operator-Audit (Metadaten, keine Payloads) | GET /admin/audit /admin/operator-audit /admin/requests/live | Kein Schreib-Scope |
billingGuthaben, Rechnungen und Abrechnungen (nur lesen, nie eine Zahlung) | GET /admin/billing /admin/billing/invoice/{id} /admin/billing/statement/{y}/{m} /admin/usage/org-spend | Kein Schreib-Scope |
scimSCIM-Bereitstellung von Personen und Gruppen aus Ihrem Identitätsanbieter | 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" } }
Nur in der Konsole
Diese Aktionen bleiben in der Konsole, egal welche Scopes ein Token hat, ein Skript kann sie also nie ausführen:
- Token verwalten.
- Einstellungen der Zwei-Faktor-Authentifizierung.
- Anbieter-Zugangsdaten (Ihre eigenen Anbieter-Schlüssel).
- Rechtliche Vereinbarungen.
- Organisation wechseln und eine eigenständige Organisation anlegen.
- Die Richtlinie ändern und ihr Versionsverlauf.
- Request-Traces, die entschlüsselte Inhalte enthalten.
- Jede Zahlungsaktion der Abrechnung.
Jeder Endpunkt, der nicht in der Tabelle oben steht, ist für Tokens auf dieselbe Weise gesperrt.
Verbrauchsexport für die Rechnungsstellung
GET /admin/v1/usage liefert den Verbrauch Ihres gesamten Organisationsbaums für einen Zeitraum, damit Sie jeden Kunden abrechnen können. Dafür brauchen Sie den Scope usage:read.
- Ein Eintrag pro Organisation: die Wurzel selbst und jeder Kunde, auch Kunden ohne Verbrauch, damit ein Abrechnungslauf jeden Kunden sieht.
- Jede Organisation hat Zeilen pro Anbieter und Modell.
- Beträge sind ganze Cent in Euro, ohne MwSt.
- Die Zahlen stammen aus derselben Abfrage wie die Abrechnungsseite der Konsole, der Export stimmt also mit Ihrer Monatsabrechnung überein.
- Nur eine Wurzel-Organisation kann ihn abrufen. Das Token einer Kunden-Organisation erhält
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), einschließlich. Geben Sie from und to zusammen an oder lassen Sie beide weg. |
| to | YYYY-MM-DD (UTC), ausschließlich, nach from. Höchstens 92 Tage. Ohne from und to erhalten Sie den Vormonat. |
| kind | agency (die Wurzel selbst), client (eine Organisation darunter) oder standalone (eine Wurzel ohne Kunden). |
| list_cents | Listenpreis des Anbieters in Cent. 0 bei eigenen Anbieter-Schlüsseln (BYOK). |
| billable_cents | Cent ohne MwSt.: was die Wurzel für diese Organisation zahlt. total_billable_cents ist ihre Summe. |
Für Ihre Rechnungen
Ein Eintrag in organisations entspricht einer Kundenrechnung, jede Zeile in lines einer Rechnungsposition. billable_cents ist ohne MwSt.: Lassen Sie Ihr Buchhaltungstool (zum Beispiel Moneybird) den Steuersatz ergänzen.
Speichern Sie period.from und period.to auf der Rechnung. Dann ist ein erneuter Lauf desselben Monats auf Ihrer Seite idempotent.
Organisationen, Mitglieder und Schlüssel anlegen
Nutzen Sie Schreib-Scopes, um Kunden aus Ihrem eigenen CRM oder Identitätsanbieter anzulegen und zu pflegen. Jede Änderung folgt denselben Validierungs-, Rollen- und Abrechnungsregeln wie die Konsole.
Kunden-Organisationen
Mit orgs:write legen Sie Kunden-Organisationen unter Ihrer Agentur an und setzen Name, Budget und Marge.
- Der Inhaber, der das Token erstellt hat, wird erster Inhaber jedes neuen Kunden. Wenn ein Token eine Organisation anlegt oder umbenennt, prüft Sluis, dass diese Person noch Inhaber ist, und antwortet sonst mit
403. - Das Anlegen einer Kunden-Organisation setzt aktive Abrechnung voraus, weil Kunden über Sie abgerechnet werden.
- Ein Agentur-Admin, der in der Konsole einen Kunden anlegt, wird dort nicht Inhaber. Er behält nur den Admin-Zugriff, den er von der Agentur erbt.
Personen
Mit members:write lädt ein Token Personen per E-Mail ein, ändert Rollen und entfernt Personen.
- Eingeladene erhalten eine Aktivierungs-E-Mail und legen ihr Passwort selbst fest. Ein Token kann kein Passwort setzen.
- Hat die Adresse schon ein Sluis-Konto, erhält die Person stattdessen eine Einladung zum Beitritt und wird erst nach der Annahme Mitglied. Die Antwort enthält
pending_acceptance: true. - Höchstens 60 Einladungen pro Stunde und Organisation. Darüber lautet die Antwort
429.
API-Schlüssel und Workloads
Mit keys:write legen Sie einen Workload an und darin einen Schlüssel. Das Geheimnis des Schlüssels wird nur einmal zurückgegeben, in der Antwort, die ihn erstellt.
SCIM
Mit scim:write stellt Ihr Identitätsanbieter Personen und Gruppen über SCIM 2.0 unter /scim/v2 bereit. Ein SCIM-Token erreicht nichts unter /admin, und kein anderes Token erreicht /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" }'
Was ein Token nicht kann
- Die Inhaber-Rolle vergeben oder die Rolle eines Inhabers ändern.
- Einen Inhaber entfernen.
- Ein Passwort setzen.
- Inhalte von Anfragen oder Antworten lesen.
Dieselbe Grenze gilt für Personen: Nur ein angemeldeter Inhaber kann die Inhaber-Rolle vergeben oder einen Inhaber ändern oder entfernen. Ein Admin erhält 403.
Ablauf, Ratenlimit, Widerruf und Audit
Ablauf und Widerruf
- Jedes Token läuft ab. Ein abgelaufenes Token antwortet mit
401, genau wie ein widerrufenes, und die Konsole zeigt es als abgelaufen an. - Zum Widerrufen nutzen Sie dieselbe Tabelle in der Konsole. Das Token funktioniert danach innerhalb von 30 Sekunden nicht mehr.
- Ein Token wird automatisch widerrufen, wenn die Person, die es erstellt hat, entfernt wird, die Inhaber-Rolle verliert oder ihr Passwort ändert.
Ratenlimit
Jedes Token darf 600 Anfragen pro Minute stellen. Darüber antwortet das Gateway mit 429 und einem Retry-After-Header: Warten Sie so viele Sekunden und versuchen Sie es erneut.
Anfragen, die wegen eines fehlenden Scopes abgelehnt werden, zählen ebenfalls zum Limit.
Audit
- Jede Änderung mit einem Token wird im Operator-Audit festgehalten, mit ID und Name des Tokens als Akteur. Die Spur nennt immer die Integration, die gehandelt hat.
- Lesen Sie es mit
GET /admin/operator-audit(Scopeaudit:read) oder in der Konsole unter Audit-Log. audit:readliefert nur Metadaten, nie Inhalte von Anfragen oder Antworten.
# 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" } } }] }
Fehler
Fehler nutzen denselben Rahmen wie der Rest der API: ein error-Objekt mit message und type. Der Statuscode sagt Ihnen, was zu tun ist.
| Status | Bedeutung |
|---|---|
400 | Ungültiger Body oder ungültige Abfrage. Die Meldung nennt das Feld. |
401 | Token fehlt, ist ungültig, widerrufen oder abgelaufen. |
402 | Die Abrechnung ist nicht aktiv, zum Beispiel beim Anlegen einer Kunden-Organisation. |
403 | Die Scopes des Tokens decken diesen Endpunkt nicht ab, oder die Rollenregeln lehnen die Aktion ab, zum Beispiel die Vergabe der Inhaber-Rolle. |
429 | Ratenlimit pro Token überschritten oder zu viele Einladungen. Retry-After Sekunden warten. |
Ein 403 mit token scope does not allow this endpoint bedeutet: Das Token ist gültig, hat aber den Scope nicht. Erstellen Sie ein neues Token mit dem richtigen Scope, statt ein bestehendes zu erweitern.