Skip to content

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.

  1. Open Settings › Admin API in the console.
  2. Enter a name for the token, 1 to 100 characters.
  3. Tick the scopes the token needs.
  4. Choose how long it lives: 1 to 365 days, 90 by default. The console offers 30, 90, 180 and 365.
  5. 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_. The sluis- 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.

  • read allows GET requests on the family.
  • write allows every method on the family and includes read.
  • Read-only families (usage, policy, audit and billing) have no write scope.
  • Scopes are fixed at creation. To change them, create a new token.
FamilyRead (GET)Write
usage
Usage per organisation (invoicing export)
GET /admin/v1/usage
GET /admin/usage
No write scope
orgs
Organisations 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
members
Members, roles and invitations (invite by email only)
GET /admin/members
POST /admin/members
PUT/DELETE /admin/members/{id}
POST /admin/members/{id}/invite
keys
API 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}
policy
The live default policy (read only)
GET /admin/policy
No write scope
audit
Audit log and the operator audit (metadata, no payloads)
GET /admin/audit
/admin/operator-audit
/admin/requests/live
No write scope
billing
Balance, 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
scim
SCIM 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"
fromYYYY-MM-DD (UTC), inclusive. Give from and to together, or leave both out.
toYYYY-MM-DD (UTC), exclusive, after from. At most 92 days. Without from and to you get the previous calendar month.
kindagency (the root itself), client (an organisation under it) or standalone (a root without clients).
list_centsProvider list price in cents. 0 for your own provider keys (BYOK).
billable_centsCents 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 403 if 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 }' …

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 (scope audit:read), or in the console under Audit log.
  • audit:read returns 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.

StatusMeaning
400Invalid body or query. The message names the field.
401Missing, invalid, revoked or expired token.
402Billing is not active, for example when creating a client organisation.
403The token's scopes do not cover this endpoint, or the role rules refuse the action, for example granting the owner role.
429Over 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.