API di amministrazione
Amministra un'organizzazione senza sessione browser: token con ambiti e scadenza per export di fatturazione, provisioning di clienti e membri e feed di audit.
Apri Impostazioni › API di amministrazione nella console
Creare un token
Crea un token nella console, poi invialo come bearer token con ogni richiesta all'API di amministrazione. Servono il ruolo di proprietario o amministratore e un indirizzo e-mail verificato.
- Apri Impostazioni › API di amministrazione nella console.
- Scrivi un nome per il token, da 1 a 100 caratteri.
- Spunta gli ambiti di cui il token ha bisogno.
- Scegli quanto dura: da 1 a 365 giorni, 90 per impostazione predefinita. La console offre 30, 90, 180 e 365.
- Crea il token e copia subito il segreto. Viene mostrato una sola volta.
Conserva il segreto nell'archivio dei segreti della tua integrazione, mai nel codice. Sluis ne tiene solo i primi 16 caratteri, così puoi riconoscere il token nell'elenco.
Chi può creare token
- Solo un proprietario può concedere un ambito di scrittura, perché un token di scrittura agisce come proprietario sull'API. Un amministratore può creare token di sola lettura.
- Solo una sessione console connessa può creare, elencare o revocare token. Un token non può mai farlo.
- Ogni token scade. Non esiste l'opzione di un token senza scadenza.
- Il segreto inizia con
sluis_admin_. Le chiavisluis-che le tue app usano per chiamare i modelli qui non funzionano.
# 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"
Autenticazione e ambiti
Invia il segreto come bearer token a ogni richiesta: Authorization: Bearer $SLUIS_ADMIN_TOKEN.
Un token appartiene all'organizzazione in cui è stato creato. Raggiunge solo gli endpoint che i suoi ambiti consentono, e tutti gli altri rispondono 403.
Come funzionano gli ambiti
Un ambito unisce una famiglia e un livello di accesso, per esempio usage:read oppure orgs:write.
readconsente richiesteGETsulla famiglia.writeconsente ogni metodo sulla famiglia e includeread.- Le famiglie di sola lettura (
usage,policy,auditebilling) non hanno ambito di scrittura. - Gli ambiti sono fissati alla creazione. Per cambiarli, crea un nuovo token.
| Famiglia | Lettura (GET) | Scrittura |
|---|---|---|
usageConsumo per organizzazione (export di fatturazione) | GET /admin/v1/usage GET /admin/usage | Nessun ambito di scrittura |
orgsOrganizzazioni e i loro clienti, budget e margini | GET /admin/orgs | POST /admin/orgs PUT /admin/orgs/{id}/name PUT /admin/orgs/{id}/budget PUT /admin/orgs/{id}/margin |
membersMembri, ruoli e inviti (invito solo via e-mail) | GET /admin/members | POST /admin/members PUT/DELETE /admin/members/{id} POST /admin/members/{id}/invite |
keysChiavi API e workload | 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} |
policyLa policy predefinita attiva (sola lettura) | GET /admin/policy | Nessun ambito di scrittura |
auditLog di audit e audit degli operatori (metadati, senza payload) | GET /admin/audit /admin/operator-audit /admin/requests/live | Nessun ambito di scrittura |
billingSaldo, fatture ed estratti (sola lettura, mai un pagamento) | GET /admin/billing /admin/billing/invoice/{id} /admin/billing/statement/{y}/{m} /admin/usage/org-spend | Nessun ambito di scrittura |
scimProvisioning SCIM di persone e gruppi dal tuo provider di identità | 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" } }
Solo nella console
Queste azioni restano nella console qualunque ambito abbia un token, quindi uno script non può mai eseguirle:
- Gestire i token.
- Impostazioni della verifica in due passaggi.
- Credenziali dei fornitori (le tue chiavi dei fornitori).
- Accordi legali.
- Cambiare organizzazione e creare un'organizzazione indipendente.
- Modificare la policy e la sua cronologia delle versioni.
- Tracce delle richieste, che contengono contenuti decifrati.
- Ogni azione di pagamento della fatturazione.
Qualsiasi endpoint che non compare nella tabella sopra è chiuso ai token allo stesso modo.
Export del consumo per la fatturazione
GET /admin/v1/usage restituisce il consumo dell'intero albero delle tue organizzazioni in un intervallo di date, per fatturare ogni cliente. Serve l'ambito usage:read.
- Una voce per organizzazione: la radice stessa e ogni cliente, anche quelli senza consumo, così un ciclo di fatturazione vede tutti i clienti.
- Ogni organizzazione ha righe per fornitore e modello.
- Gli importi sono centesimi interi in euro, IVA esclusa.
- I numeri vengono dalla stessa query della pagina Fatturazione della console, quindi l'export coincide con il tuo estratto mensile.
- Solo un'organizzazione radice può chiamarlo. Il token di un'organizzazione cliente riceve
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), incluso. Indica from e to insieme, oppure nessuno dei due. |
| to | YYYY-MM-DD (UTC), escluso, dopo from. Al massimo 92 giorni. Senza from e to ottieni il mese solare precedente. |
| kind | agency (la radice stessa), client (un'organizzazione sotto di essa) o standalone (una radice senza clienti). |
| list_cents | Prezzo di listino del fornitore, in centesimi. 0 con chiavi di fornitore proprie (BYOK). |
| billable_cents | Centesimi IVA esclusa: quanto viene addebitato alla radice per quell'organizzazione. total_billable_cents è la loro somma. |
Per le tue fatture
Una voce di organisations è una fattura cliente, e ogni riga di lines è una riga di fattura. billable_cents è IVA esclusa: lascia che il tuo strumento contabile (per esempio Moneybird) aggiunga l'aliquota.
Salva period.from e period.to sulla fattura. Così rieseguire lo stesso mese è idempotente dal tuo lato.
Provisioning di organizzazioni, membri e chiavi
Usa gli ambiti di scrittura per creare e mantenere i clienti dal tuo CRM o dal tuo provider di identità. Ogni modifica segue le stesse regole di validazione, ruolo e fatturazione della console.
Organizzazioni cliente
Con orgs:write crei organizzazioni cliente sotto la tua agenzia e ne imposti nome, budget e margine.
- Il proprietario che ha creato il token diventa il primo proprietario di ogni nuovo cliente. Quando un token crea o rinomina un'organizzazione, Sluis controlla che quella persona sia ancora proprietaria, e altrimenti risponde
403. - Creare un'organizzazione cliente richiede la fatturazione attiva, perché i clienti sono fatturati a te.
- Un amministratore di agenzia che crea un cliente nella console non ne diventa proprietario. Mantiene solo l'accesso da amministratore ereditato dall'agenzia.
Persone
Con members:write un token invita persone via e-mail, cambia i ruoli e rimuove persone.
- La persona invitata riceve un'e-mail di attivazione e sceglie la propria password. Un token non può impostare una password.
- Se l'indirizzo ha già un account Sluis, la persona riceve invece un invito a unirsi e diventa membro solo dopo averlo accettato. La risposta indica
pending_acceptance: true. - Al massimo 60 inviti all'ora per organizzazione. Oltre, la risposta è
429.
Chiavi API e workload
Con keys:write crei un workload e, al suo interno, una chiave. Il segreto della chiave viene restituito una sola volta, nella risposta che la crea.
SCIM
Con scim:write il tuo provider di identità effettua il provisioning di persone e gruppi tramite SCIM 2.0 su /scim/v2. Un token SCIM non raggiunge nulla sotto /admin, e nessun altro token raggiunge /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" }'
Cosa un token non può fare
- Concedere il ruolo di proprietario o cambiare il ruolo di un proprietario.
- Rimuovere un proprietario.
- Impostare una password.
- Leggere il contenuto di richieste o risposte.
Lo stesso limite vale per le persone: solo un proprietario connesso può concedere il ruolo di proprietario, o cambiare o rimuovere un proprietario. Un amministratore riceve 403.
Scadenza, limite di frequenza, revoca e audit
Scadenza e revoca
- Ogni token scade. Un token scaduto risponde
401, come uno revocato, e la console lo mostra come scaduto. - Per revocare un token usa la stessa tabella nella console. Smette di funzionare entro 30 secondi.
- Un token viene revocato automaticamente quando la persona che lo ha creato viene rimossa, perde il ruolo di proprietario o cambia la password.
Limite di frequenza
Ogni token può fare 600 richieste al minuto. Oltre il limite il gateway risponde 429 con un'intestazione Retry-After: attendi quei secondi e riprova.
Anche le richieste rifiutate per un ambito mancante contano nel limite.
Audit
- Ogni modifica fatta con un token viene scritta nell'audit degli operatori, con id e nome del token come autore. La traccia nomina sempre l'integrazione che ha agito.
- Leggilo con
GET /admin/operator-audit(ambitoaudit:read) oppure nella console, in Registro di audit. audit:readrestituisce solo metadati, mai il contenuto di richieste o risposte.
# 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" } } }] }
Errori
Gli errori usano lo stesso formato del resto dell'API: un oggetto error con un message e un type. Il codice di stato ti dice cosa fare.
| Stato | Significato |
|---|---|
400 | Body o query non validi. Il messaggio indica il campo. |
401 | Token mancante, non valido, revocato o scaduto. |
402 | La fatturazione non è attiva, per esempio quando crei un'organizzazione cliente. |
403 | Gli ambiti del token non coprono questo endpoint, oppure le regole di ruolo rifiutano l'azione, per esempio concedere il ruolo di proprietario. |
429 | Limite di frequenza per token superato, o troppi inviti. Attendi Retry-After secondi. |
Un 403 con token scope does not allow this endpoint significa che il token è valido ma non ha l'ambito. Crea un nuovo token con l'ambito giusto invece di ampliarne uno esistente.