Zakresy klucza
Zakres określa część API, którą klucz może wywoływać. Każda operacja w dokumentacji API deklaruje
jeden zakres, którego potrzebuje. Żądanie z kluczem, który go nie ma, jest odrzucane z 403 i kodem
api_keys.scope, zanim cokolwiek zostanie odczytane lub zmienione.
Zakresy mówią, które operacje klucz może wywoływać. Rola klucza, jego profil dostępu i kolekcje nadal decydują o tym,
które obiekty te operacje widzą: klucz z cards:write i rolą viewer nie może zmieniać kart, a klucz ograniczony do
jednej kolekcji nie widzi pozostałych.
Zakresy
| Zakres | Pozwala |
|---|---|
cards:read | Odczytywać karty, kolekcje i foldery. |
cards:write | Tworzyć, zmieniać i usuwać karty, kolekcje i foldery. |
search | Przeszukiwać bazę wiedzy (POST /v1/search). |
ask | Zadawać pytania asystentowi (POST /v1/ask, POST /v1/chat). |
import:write | Zapisywać dane we własnych źródłach organizacji: synchronizacje, pakiety i usunięcia, oraz odczytywać ich stan. Utworzenie źródła i jego kluczy wymaga zakresu admin. |
webhooks:manage | Zarządzać webhookami i odczytywać kanał zdarzeń (GET /v1/webhook-events). Obie czynności wymagają także roli admin. |
users:read | Odczytywać użytkowników i grupy. |
users:write | Zmieniać użytkowników i grupy. |
analytics:read | Odczytywać analitykę. |
audit:read | Odczytywać dziennik audytu. |
finance:read | Odczytywać raporty finansowe, faktury i płatności. |
catalog:read | Odczytywać katalog usług. |
files:read | Odczytywać wygenerowane pliki, np. wyeksportowane odpowiedzi. |
files:write | Zmieniać i usuwać wygenerowane pliki. |
permissions:manage | Przypisywać i odbierać uprawnienia do obiektów. |
admin | Ustawienia organizacji i jej klucze API. Klucz z admin ma też wszystkie pozostałe zakresy. |
Wyszukiwanie i pytania są z założenia operacjami odczytu: klucz, który może tylko odczytywać, nadal może wyszukiwać i zadawać pytania.
Wybór zakresów
Przyznawaj tylko te zakresy, których integracja używa, i żadnych innych:
| Integracja | Zakresy |
|---|---|
| Bot odpowiadający na pytania w komunikatorze | search, ask |
| Import z Twojego systemu dokumentów | cards:write (API kart) lub import:write (własne źródło) |
| Eksport do hurtowni danych | cards:read, users:read i webhooks:manage do kanału zdarzeń |
| Zakładanie kont użytkowników z Twojego systemu kadrowego | users:write |
Przekaż listę podczas tworzenia klucza:
curl -X POST https://api.sursa.com/v1/api-keys \
-H "Authorization: Bearer $SURSA_ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Support bot", "role": "viewer", "scopes": ["search", "ask"]}'Wcześniejsze zakresy
Klucze utworzone przed podziałem zakresów nadal działają. Ich zakresy read, write i admin oznaczają następujące
zestawy:
| Wcześniejszy zakres | Oznacza |
|---|---|
read | cards:read, search, ask, users:read, analytics:read, finance:read, catalog:read, files:read |
write | wszystko z read oraz cards:write, files:write, users:write, permissions:manage |
admin | każdy zakres |
Klucz utworzony bez jawnie podanych zakresów otrzymuje je na podstawie swojej roli: admin otrzymuje admin;
editor i verifier otrzymują write; viewer otrzymuje read.
Podgląd zakresów klucza
GET /v1/me zwraca zakresy klucza, który wysyła żądanie, niezależnie od tego, jakie
zakresy ten klucz ma. W przypadku klucza utworzonego bez jawnie podanych zakresów są to wcześniejsze zakresy jego
roli, np. read i write; tabela powyżej pokazuje, co oznaczają. Gdy operacja kończy się błędem api_keys.scope,
error.message wskazuje brakujący zakres.