API administracyjne
Zarządzaj organizacją bez sesji w przeglądarce: tokeny z zakresami i datą wygaśnięcia do eksportów rozliczeniowych, zakładania klientów i członków oraz kanałów audytu.
Otwórz Ustawienia › API administracyjne w konsoli
Tworzenie tokenu
Utwórz token w konsoli, a potem wysyłaj go jako bearer token z każdym żądaniem do API administracyjnego. Potrzebujesz roli właściciela lub administratora i zweryfikowanego adresu e-mail.
- Otwórz Ustawienia › API administracyjne w konsoli.
- Wpisz nazwę tokenu, od 1 do 100 znaków.
- Zaznacz zakresy, których token potrzebuje.
- Wybierz czas życia: od 1 do 365 dni, domyślnie 90. Konsola oferuje 30, 90, 180 i 365.
- Utwórz token i od razu skopiuj sekret. Pokazuje się tylko raz.
Trzymaj sekret w magazynie sekretów swojej integracji, nigdy w kodzie. Sluis zapamiętuje tylko jego pierwsze 16 znaków, żebyś mógł rozpoznać token na liście.
Kto może tworzyć tokeny
- Tylko właściciel może nadać zakres zapisu, bo token z zapisem działa w API jako właściciel. Administrator może tworzyć tokeny tylko do odczytu.
- Tokeny może tworzyć, wyświetlać i unieważniać tylko zalogowana sesja konsoli. Token nigdy tego nie zrobi.
- Każdy token wygasa. Nie ma opcji tokenu bez daty wygaśnięcia.
- Sekret zaczyna się od
sluis_admin_. Kluczesluis-, których aplikacje używają do wywołań modeli, tutaj nie działają.
# 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"
Uwierzytelnianie i zakresy
Wysyłaj sekret jako bearer token z każdym żądaniem: Authorization: Bearer $SLUIS_ADMIN_TOKEN.
Token należy do organizacji, w której został utworzony. Dociera tylko do endpointów, na które pozwalają jego zakresy, a każdy inny odpowiada 403.
Jak działają zakresy
Zakres to rodzina i poziom dostępu, na przykład usage:read albo orgs:write.
readpozwala na żądaniaGETw rodzinie.writepozwala na każdą metodę w rodzinie i obejmujeread.- Rodziny tylko do odczytu (
usage,policy,auditibilling) nie mają zakresu zapisu. - Zakresy ustala się przy tworzeniu. Żeby je zmienić, utwórz nowy token.
| Rodzina | Odczyt (GET) | Zapis |
|---|---|---|
usageZużycie na organizację (eksport do fakturowania) | GET /admin/v1/usage GET /admin/usage | Brak zakresu zapisu |
orgsOrganizacje i ich klienci, budżety i marże | GET /admin/orgs | POST /admin/orgs PUT /admin/orgs/{id}/name PUT /admin/orgs/{id}/budget PUT /admin/orgs/{id}/margin |
membersCzłonkowie, role i zaproszenia (zaproszenie tylko e-mailem) | GET /admin/members | POST /admin/members PUT/DELETE /admin/members/{id} POST /admin/members/{id}/invite |
keysKlucze API i workloady | 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} |
policyAktywna polityka domyślna (tylko odczyt) | GET /admin/policy | Brak zakresu zapisu |
auditDziennik audytu i audyt operatorów (metadane, bez treści żądań) | GET /admin/audit /admin/operator-audit /admin/requests/live | Brak zakresu zapisu |
billingSaldo, faktury i zestawienia (tylko odczyt, nigdy płatność) | GET /admin/billing /admin/billing/invoice/{id} /admin/billing/statement/{y}/{m} /admin/usage/org-spend | Brak zakresu zapisu |
scimProvisioning SCIM osób i grup z Twojego dostawcy tożsamości | 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" } }
Tylko w konsoli
Te czynności zostają w konsoli niezależnie od zakresów tokenu, więc skrypt nigdy ich nie wykona:
- Zarządzanie tokenami.
- Ustawienia uwierzytelniania dwuskładnikowego.
- Dane uwierzytelniające dostawców (Twoje własne klucze dostawców).
- Umowy prawne.
- Przełączanie organizacji i zakładanie osobnej organizacji.
- Zmiana polityki i jej historia wersji.
- Ślady żądań, które zawierają odszyfrowane treści.
- Każda czynność płatnicza w rozliczeniach.
Każdy endpoint, którego nie ma w tabeli powyżej, jest w ten sam sposób zamknięty dla tokenów.
Eksport zużycia do fakturowania
GET /admin/v1/usage zwraca zużycie całego drzewa organizacji w wybranym przedziale dat, żebyś mógł zafakturować każdego klienta. Wymaga zakresu usage:read.
- Jeden wpis na organizację: sam korzeń i każdy klient, także bez zużycia, żeby rozliczenie widziało wszystkich klientów.
- Każda organizacja ma wiersze według dostawcy i modelu.
- Kwoty to pełne centy w euro, bez VAT.
- Liczby pochodzą z tego samego zapytania co strona rozliczeń w konsoli, więc eksport zgadza się z miesięcznym zestawieniem.
- Wywołać go może tylko organizacja główna. Token organizacji klienta dostaje
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), włącznie. Podaj from i to razem albo pomiń oba. |
| to | YYYY-MM-DD (UTC), wyłącznie, po from. Najwyżej 92 dni. Bez from i to dostajesz poprzedni miesiąc kalendarzowy. |
| kind | agency (sam korzeń), client (organizacja pod nim) albo standalone (korzeń bez klientów). |
| list_cents | Cena katalogowa dostawcy w centach. 0 przy własnych kluczach dostawców (BYOK). |
| billable_cents | Centy bez VAT: ile korzeń płaci za tę organizację. total_billable_cents to ich suma. |
Do faktur
Jeden wpis w organisations to jedna faktura klienta, a każdy wiersz w lines to pozycja faktury. billable_cents jest bez VAT: stawkę podatku niech doda Twoje narzędzie księgowe (na przykład Moneybird).
Zapisz period.from i period.to na fakturze. Wtedy ponowne uruchomienie tego samego miesiąca jest po Twojej stronie idempotentne.
Zakładanie organizacji, członków i kluczy
Użyj zakresów zapisu, żeby zakładać i prowadzić klientów z własnego CRM lub dostawcy tożsamości. Każda zmiana podlega tym samym regułom walidacji, ról i rozliczeń co konsola.
Organizacje klientów
Z orgs:write zakładasz organizacje klientów pod swoją agencją i ustawiasz ich nazwę, budżet i marżę.
- Właściciel, który utworzył token, zostaje pierwszym właścicielem każdego nowego klienta. Gdy token tworzy lub zmienia nazwę organizacji, Sluis sprawdza, czy ta osoba nadal jest właścicielem, a jeśli nie, odpowiada
403. - Założenie organizacji klienta wymaga aktywnych rozliczeń, bo klienci są rozliczani na Ciebie.
- Administrator agencji, który zakłada klienta w konsoli, nie zostaje jego właścicielem. Zachowuje tylko dostęp administratora odziedziczony po agencji.
Osoby
Z members:write token zaprasza osoby e-mailem, zmienia role i usuwa osoby.
- Zaproszona osoba dostaje e-mail aktywacyjny i sama ustawia hasło. Token nie może ustawić hasła.
- Jeśli adres ma już konto Sluis, osoba dostaje zamiast tego zaproszenie do dołączenia i zostaje członkiem dopiero po jego przyjęciu. Odpowiedź zawiera
pending_acceptance: true. - Najwyżej 60 zaproszeń na godzinę na organizację. Powyżej odpowiedź to
429.
Klucze API i workloady
Z keys:write tworzysz workload, a w nim klucz. Sekret klucza wraca tylko raz, w odpowiedzi, która go tworzy.
SCIM
Z scim:write Twój dostawca tożsamości udostępnia osoby i grupy przez SCIM 2.0 pod /scim/v2. Token SCIM nie dociera do niczego pod /admin, a żaden inny token nie dociera do /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" }'
Czego token nie może
- Nadać roli właściciela ani zmienić roli właściciela.
- Usunąć właściciela.
- Ustawić hasła.
- Odczytać treści żądań ani odpowiedzi.
Ta sama granica dotyczy osób: tylko zalogowany właściciel może nadać rolę właściciela albo zmienić lub usunąć właściciela. Administrator dostaje 403.
Wygasanie, limit żądań, unieważnianie i audyt
Wygasanie i unieważnianie
- Każdy token wygasa. Wygasły token odpowiada
401, tak samo jak unieważniony, a konsola pokazuje go jako wygasły. - Żeby unieważnić token, użyj tej samej tabeli w konsoli. Przestaje działać w ciągu 30 sekund.
- Token jest unieważniany automatycznie, gdy osoba, która go utworzyła, zostanie usunięta, straci rolę właściciela albo zmieni hasło.
Limit żądań
Każdy token może wykonać 600 żądań na minutę. Powyżej limitu gateway odpowiada 429 z nagłówkiem Retry-After: odczekaj tyle sekund i spróbuj ponownie.
Do limitu liczą się też żądania odrzucone z powodu braku zakresu.
Audyt
- Każda zmiana wykonana tokenem trafia do audytu operatorów, z identyfikatorem i nazwą tokenu jako autorem. Ślad zawsze wskazuje integrację, która działała.
- Odczytasz go przez
GET /admin/operator-audit(zakresaudit:read) albo w konsoli, w Dzienniku audytu. audit:readzwraca tylko metadane, nigdy treści żądań ani odpowiedzi.
# 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" } } }] }
Błędy
Błędy mają taki sam format jak reszta API: obiekt error z polami message i type. Kod statusu mówi, co zrobić.
| Status | Znaczenie |
|---|---|
400 | Nieprawidłowe ciało lub zapytanie. Komunikat wskazuje pole. |
401 | Brak tokenu, token nieprawidłowy, unieważniony lub wygasły. |
402 | Rozliczenia nie są aktywne, na przykład przy zakładaniu organizacji klienta. |
403 | Zakresy tokenu nie obejmują tego endpointu albo reguły ról odrzucają akcję, na przykład nadanie roli właściciela. |
429 | Przekroczony limit żądań na token albo zbyt wiele zaproszeń. Odczekaj Retry-After sekund. |
403 z komunikatem token scope does not allow this endpoint oznacza, że token jest ważny, ale nie ma zakresu. Utwórz nowy token z właściwym zakresem zamiast rozszerzać istniejący.