Przejdź do treści

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.

  1. Otwórz Ustawienia › API administracyjne w konsoli.
  2. Wpisz nazwę tokenu, od 1 do 100 znaków.
  3. Zaznacz zakresy, których token potrzebuje.
  4. Wybierz czas życia: od 1 do 365 dni, domyślnie 90. Konsola oferuje 30, 90, 180 i 365.
  5. 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_. Klucze sluis-, 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.

  • read pozwala na żądania GET w rodzinie.
  • write pozwala na każdą metodę w rodzinie i obejmuje read.
  • Rodziny tylko do odczytu (usage, policy, audit i billing) nie mają zakresu zapisu.
  • Zakresy ustala się przy tworzeniu. Żeby je zmienić, utwórz nowy token.
RodzinaOdczyt (GET)Zapis
usage
Zużycie na organizację (eksport do fakturowania)
GET /admin/v1/usage
GET /admin/usage
Brak zakresu zapisu
orgs
Organizacje 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
members
Członkowie, role i zaproszenia (zaproszenie tylko e-mailem)
GET /admin/members
POST /admin/members
PUT/DELETE /admin/members/{id}
POST /admin/members/{id}/invite
keys
Klucze 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}
policy
Aktywna polityka domyślna (tylko odczyt)
GET /admin/policy
Brak zakresu zapisu
audit
Dziennik audytu i audyt operatorów (metadane, bez treści żądań)
GET /admin/audit
/admin/operator-audit
/admin/requests/live
Brak zakresu zapisu
billing
Saldo, 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
scim
Provisioning 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"
fromYYYY-MM-DD (UTC), włącznie. Podaj from i to razem albo pomiń oba.
toYYYY-MM-DD (UTC), wyłącznie, po from. Najwyżej 92 dni. Bez from i to dostajesz poprzedni miesiąc kalendarzowy.
kindagency (sam korzeń), client (organizacja pod nim) albo standalone (korzeń bez klientów).
list_centsCena katalogowa dostawcy w centach. 0 przy własnych kluczach dostawców (BYOK).
billable_centsCenty 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 }' …

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 (zakres audit:read) albo w konsoli, w Dzienniku audytu.
  • audit:read zwraca 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ć.

StatusZnaczenie
400Nieprawidłowe ciało lub zapytanie. Komunikat wskazuje pole.
401Brak tokenu, token nieprawidłowy, unieważniony lub wygasły.
402Rozliczenia nie są aktywne, na przykład przy zakładaniu organizacji klienta.
403Zakresy tokenu nie obejmują tego endpointu albo reguły ról odrzucają akcję, na przykład nadanie roli właściciela.
429Przekroczony 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.