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

Öffnen Sie in der Konsole Einstellungen › Admin API (Inhaber oder Admin, mit bestätigter E-Mail-Adresse). Benennen Sie das Token, wählen Sie die nötigen Scopes und die Laufzeit: bis zu 365 Tage, Standard 90 (die Konsole bietet 30/90/180/365). Das Geheimnis wird genau einmal angezeigt; nur die ersten Zeichen bleiben zur Wiedererkennung. Legen Sie es im Secret-Store Ihrer Integration ab, nie im Quellcode.

Schreib-Scopes kann nur ein Inhaber der Organisation vergeben, denn ein Schreib-Token handelt auf der API als Inhaber. Tokens werden nur aus einer angemeldeten Sitzung erstellt: ein Token kann nie Tokens erstellen, auflisten oder widerrufen.

# 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. Ein Token ist an die Organisation gebunden, in der es erstellt wurde, und erreicht nur die Endpunkte, die seine Scopes erlauben; alles andere antwortet mit 403. Scopes sind nach Familien gruppiert: read öffnet GET auf der Familie, write öffnet jede Methode und schließt read ein. Nur-Lese-Familien haben keinen write-Scope.

Sitzungsgebunden, was auch immer das Token trägt: Token-Verwaltung, Zwei-Faktor-Einstellungen, Anbieter- und Gateway-Zugangsdaten, rechtliche Vereinbarungen, Organisationswechsel, Richtlinien-Versionshistorie und jede Zahlungsaktion.

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

Verbrauchsexport für die Rechnungsstellung

GET /admin/v1/usage liefert den Verbrauch Ihres Organisationsbaums für ein Zeitfenster, ein Eintrag pro Organisation — auch Kunden ohne Verbrauch, damit ein Rechnungslauf jeden Kunden sieht. Beträge sind ganze Cent ohne MwSt., berechnet mit derselben Abfrage wie die Abrechnungsseite der Konsole, sodass der Export mit Ihrer Monatsabrechnung übereinstimmt.

from und to sind YYYY-MM-DD-Daten in UTC, halboffen [from, to), höchstens 92 Tage; ohne Angabe gilt der vorige Kalendermonat. Jede Organisation trägt Zeilen pro Anbieter und Modell. Speichern Sie den Zeitraum auf Ihrer Rechnung, damit ein erneuter Lauf desselben Monats bei Ihnen idempotent ist. Nur Stammorganisationen: das Token einer Kundenorganisation 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
}

Organisationen, Mitglieder und Schlüssel anlegen

Mit orgs:write legt eine Agentur Kundenorganisationen aus dem eigenen CRM an und setzt Budget und Marge; der Inhaber, der das Token erstellt hat, wird erster Inhaber jedes neuen Kunden und muss dafür weiterhin Inhaber sein. members:write lädt nur per E-Mail ein, ändert Rollen und entfernt Personen — ein Token kann weder die Inhaberrolle vergeben noch ein Passwort setzen noch einen Inhaber entfernen. keys:write legt API-Schlüssel und Workloads an.

Jede Änderung durchläuft dieselben Prüfungen, Rollen- und Abrechnungsregeln wie die Konsole: Kundenorganisationen anzulegen setzt weiterhin eine aktive Abrechnung voraus. Ein Token kann keine Inhaberrolle vergeben, keine Passwörter setzen und keine Anfrage- oder Antwortinhalte lesen.

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

Ablauf, Ratenlimit, Widerruf und Audit

Jedes in der Konsole erstellte Token läuft ab; ein abgelaufenes Token antwortet mit 401 wie ein widerrufenes, und die Konsole zeigt es als abgelaufen. Widerrufen Sie in derselben Tabelle — das Token authentifiziert innerhalb von 30 Sekunden nicht mehr. Jedes Token ist auf 600 Anfragen pro Minute begrenzt; darüber antwortet das Gateway mit 429 und einem Retry-After-Header: warten und erneut versuchen.

Jede mit einem Token vorgenommene Änderung wird ins Operator-Audit geschrieben (GET /admin/operator-audit, auch in der Konsole unter Audit-Log) mit Token-ID und -Name als Akteur, sodass die Spur immer die handelnde Integration nennt. audit:read liefert nur Metadaten — nie Anfrage- oder Antwortinhalte. Tokens werden automatisch widerrufen, wenn der Nutzer, der sie erstellt hat, entfernt wird, die Inhaberrolle verliert oder sein Passwort ändert.

# 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 dieselbe Hülle wie der Rest der API: ein error-Objekt mit message und type. Der Statuscode sagt, was zu tun ist.

Ein 403 mit „token scope does not allow this endpoint“ bedeutet: das Token existiert und ist gültig, hat aber den Scope nicht. Erstellen Sie ein neues Token mit dem richtigen Scope, statt ein bestehendes zu erweitern — Scopes stehen bei der Erstellung fest.