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
Maak een token aan in de console en stuur het als bearer token mee met elk verzoek aan de Admin API. Je hebt de rol eigenaar of beheerder nodig en een geverifieerd e-mailadres.
- Open Instellingen › Admin API in de console.
- Geef het token een naam van 1 tot 100 tekens.
- Vink de scopes aan die het token nodig heeft.
- Kies hoe lang het geldig blijft: 1 tot 365 dagen, standaard 90. De console biedt 30, 90, 180 en 365.
- Maak het token aan en kopieer meteen het geheim. Het wordt maar één keer getoond.
Bewaar het geheim in de secret store van je integratie, nooit in broncode. Sluis bewaart alleen de eerste 16 tekens, zodat je het token in de lijst herkent.
Wie tokens mag aanmaken
- Alleen een eigenaar kan een schrijfscope geven, omdat een schrijftoken via de API als eigenaar handelt. Een beheerder kan tokens met alleen leestoegang aanmaken.
- Alleen een ingelogde console-sessie kan tokens aanmaken, tonen of intrekken. Een token kan dat nooit.
- Elk token verloopt. Een token zonder vervaldatum bestaat niet.
- Het geheim begint met
sluis_admin_. Desluis-keys die je apps voor modelaanroepen gebruiken, werken hier niet.
# 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: Authorization: Bearer $SLUIS_ADMIN_TOKEN.
Een token hoort bij de organisatie waarin het is aangemaakt. Het bereikt alleen de endpoints die zijn scopes toestaan, en alle andere antwoorden met 403.
Hoe scopes werken
Een scope is een familie plus een toegangsniveau, bijvoorbeeld usage:read of orgs:write.
readstaatGET-verzoeken op de familie toe.writestaat elke methode op de familie toe en omvatread.- Families die alleen te lezen zijn (
usage,policy,auditenbilling) hebben geen schrijfscope. - Scopes liggen vast bij het aanmaken. Om ze te wijzigen, maak je een nieuw token aan.
| Familie | Lezen (GET) | Schrijven |
|---|---|---|
usageVerbruik per organisatie (facturatie-export) | GET /admin/v1/usage GET /admin/usage | Geen schrijfscope |
orgsOrganisaties en hun klanten, budgetten en marges | GET /admin/orgs | POST /admin/orgs PUT /admin/orgs/{id}/name PUT /admin/orgs/{id}/budget PUT /admin/orgs/{id}/margin |
membersLeden, rollen en uitnodigingen (alleen uitnodigen per e-mail) | GET /admin/members | POST /admin/members PUT/DELETE /admin/members/{id} POST /admin/members/{id}/invite |
keysAPI-keys en 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} |
policyDe actieve standaardpolicy (alleen lezen) | GET /admin/policy | Geen schrijfscope |
auditAuditlog en de operator-audit (metadata, geen payloads) | GET /admin/audit /admin/operator-audit /admin/requests/live | Geen schrijfscope |
billingSaldo, facturen en overzichten (alleen lezen, nooit een betaling) | GET /admin/billing /admin/billing/invoice/{id} /admin/billing/statement/{y}/{m} /admin/usage/org-spend | Geen schrijfscope |
scimSCIM-provisioning van mensen en groepen vanuit je identiteitsprovider | 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" } }
Alleen in de console
Deze acties blijven in de console, welke scopes een token ook heeft, dus een script kan ze nooit uitvoeren:
- Tokens beheren.
- Instellingen voor tweestapsverificatie.
- Provider-inloggegevens (je eigen providerkeys).
- Juridische overeenkomsten.
- Van organisatie wisselen en een zelfstandige organisatie aanmaken.
- Het beleid wijzigen en de versiegeschiedenis ervan.
- Request-traces, die ontsleutelde inhoud bevatten.
- Elke betaalactie in de facturatie.
Elk endpoint dat niet in de tabel hierboven staat, is op dezelfde manier gesloten voor tokens.
Verbruiksexport voor facturatie
GET /admin/v1/usage geeft het verbruik van je hele organisatieboom over een periode, zodat je elke klant kunt factureren. Je hebt de scope usage:read nodig.
- Eén regel per organisatie: de root zelf en elke klant, ook klanten zonder verbruik, zodat een factuurrun elke klant ziet.
- Elke organisatie heeft regels per provider en model.
- Bedragen zijn hele centen in euro, exclusief btw.
- De cijfers komen uit dezelfde query als de factuurpagina in de console, dus de export sluit aan op je maandoverzicht.
- Alleen een root-organisatie kan het aanroepen. 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
}| from | YYYY-MM-DD (UTC), inclusief. Geef from en to samen op, of laat allebei weg. |
| to | YYYY-MM-DD (UTC), exclusief, na from. Maximaal 92 dagen. Zonder from en to krijg je de vorige kalendermaand. |
| kind | agency (de root zelf), client (een organisatie eronder) of standalone (een root zonder klanten). |
| list_cents | Lijstprijs van de provider in centen. 0 bij je eigen providerkeys (BYOK). |
| billable_cents | Centen exclusief btw: wat de root voor die organisatie betaalt. total_billable_cents is de som. |
Voor je facturen
Eén regel in organisations is één klantfactuur, en elke rij in lines is een factuurregel. billable_cents is exclusief btw: laat je boekhoudtool (bijvoorbeeld Moneybird) het btw-tarief toevoegen.
Sla period.from en period.to op bij de factuur. Dan is dezelfde maand opnieuw draaien aan jouw kant idempotent.
Organisaties, leden en keys aanmaken
Gebruik schrijfscopes om klanten aan te maken en bij te houden vanuit je eigen CRM of identiteitsprovider. Elke wijziging volgt dezelfde validatie-, rol- en factuurregels als de console.
Klantorganisaties
Met orgs:write maak je klantorganisaties aan onder je bureau en stel je naam, budget en marge in.
- De eigenaar die het token heeft aangemaakt, wordt de eerste eigenaar van elke nieuwe klant. Als een token een organisatie aanmaakt of hernoemt, controleert Sluis of die persoon nog eigenaar is, en antwoordt anders met
403. - Een klantorganisatie aanmaken vereist actieve facturatie, omdat klanten op jouw rekening worden gefactureerd.
- Een bureaubeheerder die in de console een klant aanmaakt, wordt daar geen eigenaar. Hij houdt alleen de beheerderstoegang die hij van het bureau erft.
Mensen
Met members:write nodigt een token mensen uit per e-mail, wijzigt het rollen en verwijdert het mensen.
- Een uitgenodigde krijgt een activatiemail en kiest zelf een wachtwoord. Een token kan geen wachtwoord instellen.
- Heeft het adres al een Sluis-account, dan krijgt die persoon in plaats daarvan een uitnodiging om mee te doen en wordt pas lid na acceptatie. Het antwoord bevat
pending_acceptance: true. - Maximaal 60 uitnodigingen per uur per organisatie. Daarboven is het antwoord
429.
API-keys en workloads
Met keys:write maak je een workload aan en daarin een key. Het geheim van de key komt maar één keer terug, in het antwoord dat hem aanmaakt.
SCIM
Met scim:write richt je identiteitsprovider mensen en groepen in via SCIM 2.0 op /scim/v2. Een SCIM-token bereikt niets onder /admin, en geen enkel ander token bereikt /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" }'
Wat een token niet kan
- De eigenaarsrol geven of de rol van een eigenaar wijzigen.
- Een eigenaar verwijderen.
- Een wachtwoord instellen.
- De inhoud van verzoeken of antwoorden lezen.
Dezelfde grens geldt voor mensen: alleen een ingelogde eigenaar kan de eigenaarsrol geven, of een eigenaar wijzigen of verwijderen. Een beheerder krijgt 403.
Verlopen, rate limit, intrekken en audit
Verlopen en intrekken
- Elk token verloopt. Een verlopen token antwoordt
401, net als een ingetrokken token, en de console toont het als verlopen. - Om een token in te trekken gebruik je dezelfde tabel in de console. Het werkt dan binnen 30 seconden niet meer.
- Een token wordt automatisch ingetrokken als de persoon die het aanmaakte wordt verwijderd, de eigenaarsrol verliest of het wachtwoord wijzigt.
Rate limit
Elk token mag 600 verzoeken per minuut doen. Daarboven antwoordt de gateway met 429 en een Retry-After-header: wacht dat aantal seconden en probeer het opnieuw.
Verzoeken die worden geweigerd door een ontbrekende scope tellen ook mee voor de limiet.
Audit
- Elke wijziging met een token komt in de operator-audit, met id en naam van het token als actor. Het spoor noemt altijd de integratie die handelde.
- Lees het met
GET /admin/operator-audit(scopeaudit:read) of in de console onder Auditlog. audit:readgeeft alleen metadata, nooit de inhoud van verzoeken of antwoorden.
# 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 opzet als de rest van de API: een error-object met een message en een type. De statuscode vertelt wat je moet doen.
| Status | Betekenis |
|---|---|
400 | Ongeldige body of query. De melding noemt het veld. |
401 | Token ontbreekt, is ongeldig, ingetrokken of verlopen. |
402 | Facturatie is niet actief, bijvoorbeeld bij het aanmaken van een klantorganisatie. |
403 | De scopes van het token dekken dit endpoint niet, of de rolregels weigeren de actie, bijvoorbeeld het geven van de eigenaarsrol. |
429 | Rate limit per token overschreden, of te veel uitnodigingen. Wacht Retry-After seconden. |
Een 403 met token scope does not allow this endpoint betekent dat het token geldig is maar de scope mist. Maak een nieuw token aan met de juiste scope in plaats van een bestaand token te verruimen.