Zum Inhalt springen

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.

  1. Öffnen Sie in der Konsole Einstellungen › Admin-API.
  2. Geben Sie dem Token einen Namen mit 1 bis 100 Zeichen.
  3. Wählen Sie die Scopes, die das Token braucht.
  4. Wählen Sie die Laufzeit: 1 bis 365 Tage, standardmäßig 90. Die Konsole bietet 30, 90, 180 und 365.
  5. 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_. Die sluis--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.

  • read erlaubt GET-Anfragen auf der Familie.
  • write erlaubt jede Methode auf der Familie und schließt read ein.
  • Familien nur zum Lesen (usage, policy, audit und billing) haben keinen Schreib-Scope.
  • Scopes stehen bei der Erstellung fest. Um sie zu ändern, erstellen Sie ein neues Token.
FamilieLesen (GET)Schreiben
usage
Verbrauch pro Organisation (Abrechnungsexport)
GET /admin/v1/usage
GET /admin/usage
Kein Schreib-Scope
orgs
Organisationen 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
members
Mitglieder, Rollen und Einladungen (Einladung nur per E-Mail)
GET /admin/members
POST /admin/members
PUT/DELETE /admin/members/{id}
POST /admin/members/{id}/invite
keys
API-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}
policy
Die aktive Standardrichtlinie (nur lesen)
GET /admin/policy
Kein Schreib-Scope
audit
Audit-Log und Operator-Audit (Metadaten, keine Payloads)
GET /admin/audit
/admin/operator-audit
/admin/requests/live
Kein Schreib-Scope
billing
Guthaben, 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
scim
SCIM-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"
fromYYYY-MM-DD (UTC), einschließlich. Geben Sie from und to zusammen an oder lassen Sie beide weg.
toYYYY-MM-DD (UTC), ausschließlich, nach from. Höchstens 92 Tage. Ohne from und to erhalten Sie den Vormonat.
kindagency (die Wurzel selbst), client (eine Organisation darunter) oder standalone (eine Wurzel ohne Kunden).
list_centsListenpreis des Anbieters in Cent. 0 bei eigenen Anbieter-Schlüsseln (BYOK).
billable_centsCent 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 }' …

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 (Scope audit:read) oder in der Konsole unter Audit-Log.
  • audit:read liefert 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.

StatusBedeutung
400Ungültiger Body oder ungültige Abfrage. Die Meldung nennt das Feld.
401Token fehlt, ist ungültig, widerrufen oder abgelaufen.
402Die Abrechnung ist nicht aktiv, zum Beispiel beim Anlegen einer Kunden-Organisation.
403Die Scopes des Tokens decken diesen Endpunkt nicht ab, oder die Rollenregeln lehnen die Aktion ab, zum Beispiel die Vergabe der Inhaber-Rolle.
429Ratenlimit 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.