Vai al contenuto

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.

  1. Apri Impostazioni › API di amministrazione nella console.
  2. Scrivi un nome per il token, da 1 a 100 caratteri.
  3. Spunta gli ambiti di cui il token ha bisogno.
  4. Scegli quanto dura: da 1 a 365 giorni, 90 per impostazione predefinita. La console offre 30, 90, 180 e 365.
  5. 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 chiavi sluis- 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.

  • read consente richieste GET sulla famiglia.
  • write consente ogni metodo sulla famiglia e include read.
  • Le famiglie di sola lettura (usage, policy, audit e billing) non hanno ambito di scrittura.
  • Gli ambiti sono fissati alla creazione. Per cambiarli, crea un nuovo token.
FamigliaLettura (GET)Scrittura
usage
Consumo per organizzazione (export di fatturazione)
GET /admin/v1/usage
GET /admin/usage
Nessun ambito di scrittura
orgs
Organizzazioni 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
members
Membri, ruoli e inviti (invito solo via e-mail)
GET /admin/members
POST /admin/members
PUT/DELETE /admin/members/{id}
POST /admin/members/{id}/invite
keys
Chiavi 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}
policy
La policy predefinita attiva (sola lettura)
GET /admin/policy
Nessun ambito di scrittura
audit
Log di audit e audit degli operatori (metadati, senza payload)
GET /admin/audit
/admin/operator-audit
/admin/requests/live
Nessun ambito di scrittura
billing
Saldo, 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
scim
Provisioning 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"
fromYYYY-MM-DD (UTC), incluso. Indica from e to insieme, oppure nessuno dei due.
toYYYY-MM-DD (UTC), escluso, dopo from. Al massimo 92 giorni. Senza from e to ottieni il mese solare precedente.
kindagency (la radice stessa), client (un'organizzazione sotto di essa) o standalone (una radice senza clienti).
list_centsPrezzo di listino del fornitore, in centesimi. 0 con chiavi di fornitore proprie (BYOK).
billable_centsCentesimi 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 }' …

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 (ambito audit:read) oppure nella console, in Registro di audit.
  • audit:read restituisce 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.

StatoSignificato
400Body o query non validi. Il messaggio indica il campo.
401Token mancante, non valido, revocato o scaduto.
402La fatturazione non è attiva, per esempio quando crei un'organizzazione cliente.
403Gli ambiti del token non coprono questo endpoint, oppure le regole di ruolo rifiutano l'azione, per esempio concedere il ruolo di proprietario.
429Limite 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.