Admin API

Beheer een organisatie zonder browsersessie: tokens met scopes en een vervaldatum voor facturatie-exports, het aanmaken van klanten en leden, en auditfeeds.

Open Instellingen › Admin API in de console

Een token aanmaken

Open Instellingen › Admin API in de console (eigenaar of admin, met een geverifieerd e-mailadres). Geef het token een naam, vink de scopes aan die het nodig heeft en kies hoe lang het geldig is: tot 365 dagen, standaard 90 (de console biedt 30/90/180/365). Het geheim wordt precies één keer getoond; alleen de eerste tekens blijven bewaard ter herkenning. Bewaar het in de secret store van je integratie, nooit in code.

Schrijf-scopes kan alleen een eigenaar van de organisatie toekennen, omdat een schrijf-token op de API als eigenaar handelt. Tokens worden alleen vanuit een ingelogde sessie aangemaakt: een token kan nooit tokens aanmaken, tonen of intrekken.

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

Authenticatie en scopes

Stuur het geheim als bearer-token mee met elk verzoek. Een token is gebonden aan de organisatie waarin het is aangemaakt en bereikt alleen de endpoints die zijn scopes toestaan; al het andere antwoordt 403. Scopes zijn gegroepeerd per familie: read opent GET op de familie, write opent elke method en impliceert read. Alleen-lezen-families hebben geen write-scope.

Alleen via een sessie, wat het token ook draagt: tokenbeheer, tweefactorinstellingen, provider- en gateway-credentials, juridische overeenkomsten, wisselen van organisatie, versiegeschiedenis van de policy en elke betaalactie.

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

Verbruiksexport voor facturatie

GET /admin/v1/usage geeft het verbruik van je organisatieboom voor een periode, één regel per organisatie — ook klanten zonder verbruik, zodat een factuurrun elke klant ziet. Bedragen zijn hele centen exclusief btw, berekend met dezelfde query als de facturatiepagina in de console, zodat de export aansluit op je maandoverzicht.

from en to zijn YYYY-MM-DD-datums in UTC, half-open [from, to), maximaal 92 dagen; weggelaten beslaan ze de vorige kalendermaand. Elke organisatie bevat regels per provider en model. Sla de periode op je factuur op, zodat een herhaalde run van dezelfde maand aan jouw kant idempotent is. Alleen hoofdorganisaties: het token van een klantorganisatie krijgt 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
}

Organisaties, leden en keys aanmaken

Met orgs:write maakt een bureau klantorganisaties aan en zet het hun budget en marge vanuit het eigen CRM; de eigenaar die het token aanmaakte wordt de eerste eigenaar van elke nieuwe klant en moet dus nog eigenaar zijn. members:write nodigt alleen per e-mail uit, wijzigt rollen en verwijdert mensen — een token kan de eigenaarsrol niet toekennen, geen wachtwoord zetten en geen eigenaar verwijderen. keys:write maakt API-keys en workloads aan.

Elke wijziging doorloopt dezelfde validatie, rol- en facturatieregels als de console: klantorganisaties aanmaken vereist nog steeds actieve facturatie. Een token kan de eigenaarsrol niet toekennen, geen wachtwoorden zetten en geen request- of response-payloads lezen.

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

Verlopen, rate limit, intrekken en audit

Elk in de console aangemaakt token verloopt; een verlopen token antwoordt 401, precies als een ingetrokken token, en de console toont het als verlopen. Intrekken doe je in dezelfde tabel — het token authenticeert binnen 30 seconden niet meer. Elk token is beperkt tot 600 verzoeken per minuut; daarboven antwoordt de gateway 429 met een Retry-After-header: wacht en probeer opnieuw.

Elke wijziging die met een token wordt gedaan komt in de operator-audit (GET /admin/operator-audit, ook in de console onder Auditlog) met het id en de naam van het token als actor, zodat het spoor altijd de integratie noemt die handelde. audit:read geeft alleen metadata — nooit request- of response-payloads. Tokens worden automatisch ingetrokken wanneer de gebruiker die ze aanmaakte wordt verwijderd, de eigenaarsrol verliest of zijn wachtwoord wijzigt.

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

Fouten

Fouten gebruiken dezelfde envelop als de rest van de API: een error-object met een message en een type. De statuscode zegt wat je moet doen.

Een 403 met "token scope does not allow this endpoint" betekent dat het token bestaat en geldig is, maar de scope mist: maak een nieuw token met de juiste scope in plaats van een bestaand token te verbreden — scopes liggen vast bij aanmaak.