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 › Admin API w konsoli

Tworzenie tokenu

Otwórz Ustawienia › Admin API w konsoli (właściciel lub admin, ze zweryfikowanym adresem e-mail). Nazwij token, zaznacz potrzebne zakresy i wybierz czas życia: do 365 dni, domyślnie 90 (konsola oferuje 30/90/180/365). Sekret jest pokazywany dokładnie raz; zachowywane są tylko jego pierwsze znaki do rozpoznania. Przechowuj go w magazynie sekretów integracji, nigdy w kodzie.

Zakresy zapisu może nadać tylko właściciel organizacji, bo token z zapisem działa w API jako właściciel. Tokeny tworzy się wyłącznie z zalogowanej sesji: token nigdy nie może tworzyć, listować ani unieważniać tokenów.

# 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 przy każdym żądaniu. Token jest związany z organizacją, w której go utworzono, i sięga tylko endpointów dozwolonych przez jego zakresy; wszystko inne odpowiada 403. Zakresy są pogrupowane w rodziny: read otwiera GET na rodzinie, write otwiera każdą metodę i zawiera read. Rodziny tylko do odczytu nie mają zakresu write.

Tylko z sesji, niezależnie od tokenu: zarządzanie tokenami, ustawienia drugiego składnika, poświadczenia dostawców i bram, umowy prawne, przełączanie organizacji, historia wersji polityki i każda akcja płatności.

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

Eksport zużycia do fakturowania

GET /admin/v1/usage zwraca zużycie drzewa Twoich organizacji w oknie czasowym, jeden wpis na organizację — łącznie z klientami bez zużycia, aby przebieg fakturowania widział każdego klienta. Kwoty to całkowite centy bez VAT, liczone tym samym zapytaniem co strona rozliczeń w konsoli, więc eksport zgadza się z miesięcznym zestawieniem.

from i to to daty YYYY-MM-DD w UTC, przedział półotwarty [from, to), najwyżej 92 dni; pominięte obejmują poprzedni miesiąc kalendarzowy. Każda organizacja niesie wiersze per dostawca i model. Zapisz okres na fakturze, aby ponowne uruchomienie tego samego miesiąca było po Twojej stronie idempotentne. Tylko organizacje główne: token organizacji klienckiej 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
}

Zakładanie organizacji, członków i kluczy

Z orgs:write agencja zakłada organizacje klienckie i ustawia ich budżet oraz marżę z własnego CRM; właściciel, który utworzył token, staje się pierwszym właścicielem każdego nowego klienta, więc musi nadal być właścicielem. members:write zaprasza tylko e-mailem, zmienia role i usuwa osoby — token nie może nadać roli właściciela, ustawić hasła ani usunąć właściciela. keys:write zakłada klucze API i obciążenia.

Każda zmiana przechodzi te same walidacje, reguły ról i rozliczeń co konsola: zakładanie organizacji klienckich nadal wymaga aktywnych rozliczeń. Token nie może nadać roli właściciela, ustawiać haseł ani czytać treści żądań i odpowiedzi.

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

Wygasanie, limit żądań, unieważnianie i audyt

Każdy token utworzony w konsoli wygasa; wygasły token odpowiada 401 dokładnie jak unieważniony, a konsola pokazuje go jako wygasły. Unieważnij w tej samej tabeli — token przestaje uwierzytelniać w ciągu 30 sekund. Każdy token ma limit 600 żądań na minutę; powyżej brama odpowiada 429 z nagłówkiem Retry-After: odczekaj i ponów.

Każda zmiana wykonana tokenem trafia do audytu operatorów (GET /admin/operator-audit, także w konsoli w Dzienniku audytu) z id i nazwą tokenu jako aktorem, więc ślad zawsze wskazuje integrację, która działała. audit:read zwraca tylko metadane — nigdy treści żądań ani odpowiedzi. Tokeny są unieważniane automatycznie, gdy użytkownik, który je utworzył, zostanie usunięty, straci rolę właściciela lub zmieni hasło.

# 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 używają tej samej koperty co reszta API: obiekt error z message i type. Kod statusu mówi, co zrobić.

403 z "token scope does not allow this endpoint" oznacza, że token istnieje i jest ważny, ale nie ma zakresu: utwórz nowy token z właściwym zakresem zamiast rozszerzać istniejący — zakresy są ustalane przy tworzeniu.