Admin API
Administer an organisation without a browser session: scoped, expiring tokens for invoicing exports, provisioning clients and members, and audit feeds.
Open Settings › Admin API in the console
Create a token
Create a token in the console, then send it as a bearer token with every Admin API request. You need the owner or admin role and a verified email address.
- Open Settings › Admin API in the console.
- Enter a name for the token, 1 to 100 characters.
- Tick the scopes the token needs.
- Choose how long it lives: 1 to 365 days, 90 by default. The console offers 30, 90, 180 and 365.
- Create the token and copy the secret straight away. It is shown only once.
Keep the secret in your integration's secret store, never in source. Sluis keeps only its first 16 characters, so you can recognise the token in the list.
Who can create tokens
- Only an owner can grant a write scope, because a write token acts as owner on the API. An admin can create read-only tokens.
- Only a signed-in console session can create, list or revoke tokens. A token can never do this.
- Every token expires. There is no option for a token that never expires.
- The secret starts with
sluis_admin_. Thesluis-keys your apps use for model calls do not work here.
# 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"
Authentication and scopes
Send the secret as a bearer token with every request: Authorization: Bearer $SLUIS_ADMIN_TOKEN.
A token belongs to the organisation it was created in. It reaches only the endpoints its scopes allow, and every other endpoint answers 403.
How scopes work
A scope is a family plus an access level, for example usage:read or orgs:write.
readallowsGETrequests on the family.writeallows every method on the family and includesread.- Read-only families (
usage,policy,auditandbilling) have no write scope. - Scopes are fixed at creation. To change them, create a new token.
| Family | Read (GET) | Write |
|---|---|---|
usageUsage per organisation (invoicing export) | GET /admin/v1/usage GET /admin/usage | No write scope |
orgsOrganisations and their clients, budgets and margins | GET /admin/orgs | POST /admin/orgs PUT /admin/orgs/{id}/name PUT /admin/orgs/{id}/budget PUT /admin/orgs/{id}/margin |
membersMembers, roles and invitations (invite by email only) | GET /admin/members | POST /admin/members PUT/DELETE /admin/members/{id} POST /admin/members/{id}/invite |
keysAPI keys and 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} |
policyThe live default policy (read only) | GET /admin/policy | No write scope |
auditAudit log and the operator audit (metadata, no payloads) | GET /admin/audit /admin/operator-audit /admin/requests/live | No write scope |
billingBalance, invoices and statements (read only, never a payment) | GET /admin/billing /admin/billing/invoice/{id} /admin/billing/statement/{y}/{m} /admin/usage/org-spend | No write scope |
scimSCIM provisioning of people and groups from your identity provider | 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" } }
Console only
These actions stay in the console whatever scopes a token has, so a script can never run them:
- Managing tokens.
- Two-factor settings.
- Provider credentials (your own provider keys).
- Legal agreements.
- Switching organisation, and creating a separate (standalone) organisation.
- Changing the policy, and its version history.
- Request traces, which contain decrypted payloads.
- Every billing payment action.
Any endpoint that is not in the table above is closed to tokens in the same way.
Usage export for invoicing
GET /admin/v1/usage returns the usage of your whole organisation tree for a date range, so you can invoice each client. It needs the usage:read scope.
- One entry per organisation: the root itself and every client, including clients without usage, so an invoice run sees every customer.
- Each organisation has lines per provider and model.
- Amounts are whole cents in euros, excluding VAT.
- The numbers come from the same query as the console billing page, so the export matches your monthly statement.
- Only a root organisation can call it. A client organisation's token gets
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), inclusive. Give from and to together, or leave both out. |
| to | YYYY-MM-DD (UTC), exclusive, after from. At most 92 days. Without from and to you get the previous calendar month. |
| kind | agency (the root itself), client (an organisation under it) or standalone (a root without clients). |
| list_cents | Provider list price in cents. 0 for your own provider keys (BYOK). |
| billable_cents | Cents excluding VAT: what the root is charged for that organisation. total_billable_cents is their sum. |
Using it for invoices
One entry in organisations is one customer invoice, and each row in lines is an invoice line. billable_cents excludes VAT, so let your accounting tool (Moneybird, for example) add the tax rate.
Store period.from and period.to on the invoice. Then running the same month again is idempotent on your side.
Provisioning organisations, members and keys
Use write scopes to set up and maintain customers from your own CRM or identity provider. Every change follows the same validation, role and billing rules as the console.
Client organisations
With orgs:write you create client organisations under your agency and set their name, budget and margin.
- The owner who created the token becomes the first owner of each new client. When a token creates or renames an organisation, Sluis checks that this person is still an owner, and answers
403if not. - Creating a client organisation needs active billing, because clients are billed to you.
- An agency admin who creates a client in the console does not become its owner. They keep only the admin access they inherit from the agency.
People
With members:write a token invites people by email, changes roles and removes people.
- An invited person gets an activation email and sets their own password. A token cannot set a password.
- If the address already has a Sluis account, that person gets a join invitation instead and becomes a member only after accepting. The response says
pending_acceptance: true. - At most 60 invitations per hour per organisation. Over that, the answer is
429.
API keys and workloads
With keys:write you create a workload, then a key inside it. The key's secret is returned once, in the response that creates it.
SCIM
With scim:write your identity provider provisions people and groups through SCIM 2.0 at /scim/v2. A SCIM token reaches nothing under /admin, and no other token reaches /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" }'
What a token cannot do
- Grant the owner role, or change an owner's role.
- Remove an owner.
- Set a password.
- Read request or response payloads.
The same ceiling applies to people: only a signed-in owner can grant the owner role, or change or remove an owner. An admin gets 403.
Expiry, rate limit, revocation and audit
Expiry and revocation
- Every token expires. An expired token answers
401, like a revoked one, and the console lists it as expired. - To revoke a token, use the same table in the console. It stops working within 30 seconds.
- A token is revoked automatically when the person who created it is removed, loses the owner role or changes their password.
Rate limit
Each token may make 600 requests per minute. Over the limit the gateway answers 429 with a Retry-After header: wait that many seconds, then retry.
Requests refused for a missing scope count towards the limit too.
Audit
- Every change made with a token is written to the operator audit, with the token's id and name as the actor. The trail always names the integration that acted.
- Read it with
GET /admin/operator-audit(scopeaudit:read), or in the console under Audit log. audit:readreturns metadata only, never request or response payloads.
# 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" } } }] }
Errors
Errors use the same envelope as the rest of the API: an error object with a message and a type. The status code tells you what to do.
| Status | Meaning |
|---|---|
400 | Invalid body or query. The message names the field. |
401 | Missing, invalid, revoked or expired token. |
402 | Billing is not active, for example when creating a client organisation. |
403 | The token's scopes do not cover this endpoint, or the role rules refuse the action, for example granting the owner role. |
429 | Over the per-token rate limit, or too many invitations. Wait Retry-After seconds. |
A 403 with token scope does not allow this endpoint means the token is valid but lacks the scope. Create a new token with the right scope instead of widening an existing one.