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 › Admin API nella console

Creare un token

Apri Impostazioni › Admin API nella console (proprietario o admin, con indirizzo e-mail verificato). Dai un nome al token, seleziona gli ambiti necessari e scegli la durata: fino a 365 giorni, 90 per impostazione predefinita (la console offre 30/90/180/365). Il segreto viene mostrato una sola volta; ne restano solo i primi caratteri per riconoscerlo. Conservalo nel secret store della tua integrazione, mai nel codice.

Gli ambiti in scrittura possono essere concessi solo da un proprietario dell'organizzazione, perché un token in scrittura agisce come proprietario sull'API. I token vengono creati solo da una sessione autenticata: un token non può mai creare, elencare o revocare token.

# 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. Un token è legato all'organizzazione in cui è stato creato e raggiunge solo gli endpoint consentiti dai suoi ambiti; tutto il resto risponde 403. Gli ambiti sono raggruppati per famiglia: read apre GET sulla famiglia, write apre ogni metodo e implica read. Le famiglie di sola lettura non hanno ambito write.

Solo da sessione, qualunque sia il token: gestione dei token, impostazioni del secondo fattore, credenziali di provider e gateway, accordi legali, cambio di organizzazione, cronologia delle versioni della policy e ogni azione di pagamento.

# a token without the scope for this endpoint
{
  "error": {
    "message": "token scope does not allow this endpoint",
    "type": "sluis_error"
  }
}

Export del consumo per la fatturazione

GET /admin/v1/usage restituisce il consumo del tuo albero di organizzazioni in una finestra, una voce per organizzazione — inclusi i clienti senza consumo, così un ciclo di fatturazione vede ogni cliente. Gli importi sono centesimi interi IVA esclusa, calcolati con la stessa query della pagina Fatturazione della console: l'export si riconcilia con il tuo estratto mensile.

from e to sono date YYYY-MM-DD in UTC, intervallo semiaperto [from, to), al massimo 92 giorni; se omesse coprono il mese solare precedente. Ogni organizzazione porta righe per provider e modello. Salva il periodo sulla fattura così una nuova esecuzione dello stesso mese è idempotente dal tuo lato. Solo organizzazioni radice: 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
}

Provisioning di organizzazioni, membri e chiavi

Con orgs:write un'agenzia crea organizzazioni cliente e ne imposta budget e margine dal proprio CRM; il proprietario che ha creato il token diventa il primo proprietario di ogni nuovo cliente, quindi deve essere ancora proprietario. members:write invita solo via e-mail, cambia ruoli e rimuove persone — un token non può concedere il ruolo di proprietario, impostare una password né rimuovere un proprietario. keys:write crea chiavi API e workload.

Ogni modifica segue le stesse validazioni, regole di ruolo e di fatturazione della console: creare organizzazioni cliente richiede ancora una fatturazione attiva. Un token non può concedere il ruolo di proprietario, impostare password né leggere il contenuto di richieste e risposte.

# 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" }'

Scadenza, limite di frequenza, revoca e audit

Ogni token creato nella console scade; un token scaduto risponde 401 esattamente come uno revocato, e la console lo elenca come scaduto. Revocalo dalla stessa tabella — smette di autenticare entro 30 secondi. Ogni token è limitato a 600 richieste al minuto; oltre, il gateway risponde 429 con un header Retry-After: attendi e riprova.

Ogni modifica effettuata con un token viene scritta nell'audit degli operatori (GET /admin/operator-audit, anche nella console sotto Log di audit) con id e nome del token come attore, così la traccia nomina sempre l'integrazione che ha agito. audit:read restituisce solo metadati — mai il contenuto di richieste o risposte. I token vengono revocati automaticamente quando l'utente che li ha creati viene rimosso, perde il ruolo di proprietario o cambia la password.

# 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 involucro del resto dell'API: un oggetto error con message e type. Il codice di stato dice cosa fare.

Un 403 con "token scope does not allow this endpoint" significa che il token esiste ed è valido ma non ha l'ambito: crea un nuovo token con l'ambito giusto invece di ampliarne uno esistente — gli ambiti sono fissati alla creazione.