Zakresy
Pełna lista zakresów klucza API, wildcardy i zakresy, których żaden wildcard nie przyzna.
Klucz API nosi jawną listę zakresów i musi mieć co najmniej jeden. Każda trasa deklaruje zakres, którego wymaga — klucz bez niego dostaje 403 API_KEY_INSUFFICIENT_SCOPE, a w details wraca requiredScope i availableScopes.
Dostępne zakresy
Opisy poniżej są dokładnie tymi, które widzisz w Portalu przy generowaniu klucza.
| Zakres | Opis | Gdzie działa |
|---|---|---|
tasks.read | Odczyt zadań | GET /tasks, GET /tasks/{taskId} |
tasks.write | Tworzenie, edycja i usuwanie zadań | POST /tasks, PATCH /tasks/{taskId}, DELETE /tasks/{taskId} |
users.read | Odczyt użytkowników | GET /users |
tags.read | Odczyt tagów | GET /tags |
calls.read | Odczyt połączeń telefonicznych | GET /calls |
thulium.initialize-call | Inicjowanie połączeń wychodzących przez API kompatybilne z Thulium | endpoint zgodności z Thulium |
contact-requests.read | Odczyt próśb kontaktu | GET /contact-requests |
contact-requests.write | Tworzenie i zarządzanie prośbami kontaktu | POST /contact-requests |
bots.read | Odczyt botów głosowych, ich konfiguracji, przepływów i gotowości | GET /bots…, konfiguracja, przepływy, procedury, gotowość |
bots.write | Tworzenie i konfiguracja botów głosowych, przepływów, publikacji i wycofań | POST/PATCH/PUT na botach, konfiguracji, publikacji, wycofaniach, przepływach, procedurach, attach-bot |
knowledge.read | Odczyt baz wiedzy botów i ich źródeł | GET /bots/{botId}/knowledge… |
knowledge.write | Tworzenie, edycja i usuwanie źródeł wiedzy botów | POST/PATCH/DELETE na źródłach wiedzy |
locations.read | Odczyt lokalizacji | GET /locations… |
locations.write | Tworzenie i edycja lokalizacji | POST /locations, PATCH /locations/{locationId} |
phone-numbers.read | Odczyt numerów telefonów dostępnych do przypisania botom | GET /phone-numbers |
model-catalog.read | Odczyt rekomendowanych ustawień botów (modele konfiguruje zespół Mediflo) | GET /model-catalog |
webhooks.manage | Zarządzanie punktami końcowymi webhooków i podgląd dostarczeń | /webhook-endpoints/*, /webhook-deliveries/* |
webhook-payloads.read | Odczyt treści dostarczonych do punktu końcowego webhooka (mogą zawierać dane osobowe, w tym dane wrażliwe) | GET /webhook-deliveries/{deliveryId}/payload |
bot-calls.read | Odczyt sesji botów, ich telemetrii i transkrypcji | GET /bot-sessions…, /telemetry, /transcript |
bot-calls.write | Zlecanie wychodzących połączeń bota | POST /bot-sessions |
tickets.read | Odczyt zgłoszeń do wsparcia Mediflo | GET /tickets, GET /tickets/{ticketId} |
tickets.write | Zgłaszanie problemów do wsparcia i dołączanie sesji botów | POST /tickets, POST /tickets/{ticketId}/sessions |
trunks.read | Odczyt trunków SIP, obsługiwanych operatorów i diagnostyki trunków (nigdy haseł) | narzędzia MCP list_trunk_providers, list_trunks, get_trunk |
trunks.write | Tworzenie i edycja trunków SIP oraz ich numerów (tylko administratorzy) | narzędzia MCP tworzące i edytujące trunki |
ivr-flows.read | Odczyt drzewek IVR, ich wersji i przypisań do numerów | narzędzia MCP list_ivr_flows, get_ivr_flow, get_ivr_flow_schema, list_ivr_audio_assets, validate_ivr_flow |
ivr-flows.write | Edycja, aktywacja i przypisywanie drzewek IVR do numerów (tylko administratorzy) | narzędzia MCP tworzące, zapisujące, aktywujące i przypisujące drzewka IVR |
queues.read | Odczyt kolejek połączeń i ich członków | narzędzia MCP list_queues, get_queue, list_queue_member_candidates |
queues.write | Konfiguracja kolejek, ich członków i numerów kolejki zewnętrznej (tylko administratorzy) | narzędzia MCP konfigurujące kolejki, członków, ich godziny i numery kolejki zewnętrznej |
cases.read | Odczyt spraw klientów, ich notatek i powiązanych rekordów | GET /cases…, GET /cases/{caseId}/comments; narzędzia MCP list_cases, get_case |
cases.write | Zakładanie i edycja spraw klientów, dodawanie notatek i powiązań. Zawiera odczyt. | POST /cases, PATCH /cases/{caseId}, POST /cases/{caseId}/comments, POST/DELETE na powiązaniach; narzędzia MCP create_case, update_case |
bot-calls.read celowo obejmuje sesje, telemetrię i transkrypcje jednym zakresem. Podział, który ma znaczenie, jest per endpoint, a nie per zakres: klient, który chce diagnostyki bez treści rozmowy, woła /telemetry i po prostu nigdy nie woła /transcript.
Zakresy spraw — cases.read, cases.write — są dostępne tylko w organizacjach, które mają włączone sprawy. Gdzie spraw nie ma, Portal ich nie pokazuje przy generowaniu klucza, a trasy odpowiadają 404 TENANT_MODULE_UNAVAILABLE (typ działalności bez spraw) albo 403 FEATURE_NOT_AVAILABLE (sprawy jeszcze niewłączone).
Zakresy telefonii — trunks.*, ivr-flows.*, queues.* — działają wyłącznie w serwerze MCP. Dotyczą konfiguracji Twojej organizacji: jej własnych trunków SIP, drzewek IVR i kolejek. Zakres *.write obejmuje też odpowiadający mu *.read, bo każde narzędzie zapisujące potrzebuje znacznika, który zwraca tylko odczyt (np. updatedAt wersji roboczej). Odwrotnie nigdy: klucz tylko do odczytu nie zmieni routingu połączeń.
Czego nie ma i nie będzie
Nie istnieje users.write ani tags.write — żadna trasa ich nigdy nie zaimplementowała, a przyznanie zakresu, który po cichu nic nie robi, jest gorsze niż odmowa. Tak samo nie ma phone-numbers.write ani model-catalog.write: numery dopisujesz do trunka swojej organizacji pod trunks.write, zakup numerów i pula numerów platformy zostają po stronie zespołu Mediflo, a katalog modeli prowadzi zespół Mediflo. Tryb routingu SIP, trunki z rejestracją centrali (peer) i usuwanie trunków też zostają w Portalu. Nie ma też DELETE /bots/{botId} — usuwanie bota jest nieodwracalne, więc zostaje w Portalu.
Przepływy rozmowy, wersje robocze konfiguracji i publikacje nie mają własnych zakresów: są dziećmi bota i jadą pod bots.read / bots.write.
Wildcardy
| Wildcard | Przyznaje |
|---|---|
tasks.* | Wszystkie operacje na zadaniach |
users.* | Wszystkie operacje na użytkownikach |
tags.* | Wszystkie operacje na tagach |
calls.* | Wszystkie operacje na połączeniach |
thulium.* | Wszystkie operacje kompatybilne z Thulium |
contact-requests.* | Wszystkie operacje na prośbach kontaktu |
bots.* | Wszystkie operacje na botach głosowych (konfiguracja, przepływy, publikacja) |
knowledge.* | Wszystkie operacje na bazie wiedzy bota |
locations.* | Wszystkie operacje na lokalizacjach |
phone-numbers.* | Wszystkie operacje na numerach telefonów |
model-catalog.* | Wszystkie operacje na katalogu modeli |
webhooks.* | Wszystkie operacje na webhookach |
bot-calls.* | Wszystkie operacje odczytu sesji botów (zlecanie połączeń wymaga bot-calls.write wprost) |
tickets.* | Wszystkie operacje na zgłoszeniach do wsparcia |
* oraz *.* | Pełny dostęp do wszystkich zasobów — poza zakresami tylko na wprost |
Wildcard zasobowy działa wyłącznie dla zasobów z tabeli wyżej.
Zakresy tylko na wprost
Żaden wildcard ich nie przyzna
Ani *, ani *.*, ani wildcard zasobowy. Klucz musi wymienić taki zakres z nazwy, inaczej trasa odpowiada 403.
| Zakres | Dlaczego osobno |
|---|---|
webhook-payloads.read | Zwraca dostarczoną treść — projekcję zdarzenia wysłanego pod dany endpoint. Dla endpointu, który włączył bloki outcome albo transcript, to dane osobowe, w tym dane wrażliwe. Zarządzanie endpointem nie może z automatu oznaczać czytania tego, co przez niego przepłynęło. |
bot-calls.write | Sprawia, że dzwoni czyjś telefon. Wprowadzony razem ze swoją trasą, żeby żaden istniejący klucz z * czy bot-calls.* nie odziedziczył możliwości zlecania połączeń. |
trunks.read, trunks.write | Konfiguracja trunków SIP organizacji. Zapis zmienia routing połączeń na żywo i nadaje go tylko administrator — przy wydawaniu klucza oraz nigdy przez logowanie asystenta (OAuth). |
ivr-flows.read, ivr-flows.write | Drzewka IVR i ich przypisania do numerów. Aktywacja wersji i przypisanie numeru działają od następnego połączenia; zapis nadaje tylko administrator. |
queues.read, queues.write | Kolejki, ich członkowie i prywatne numery, na które dzwoni kolejka zewnętrzna. Zapis nadaje tylko administrator; odczyty pokazują te numery wyłącznie zamaskowane. |
cases.read, cases.write | Tytuły, opisy, lokalizacje i notatki spraw to dane osobowe klientów. Wprowadzone razem ze swoimi trasami, żeby żaden istniejący klucz z * nie zaczął ich czytać dziedziczeniem. cases.write obejmuje cases.read. |
Zakres, który przyszedł dziedziczeniem, nigdy nie został świadomie przyznany. To dokładnie ten scenariusz, któremu ta lista zapobiega.
Walidacja przy tworzeniu klucza
Zakresy są sprawdzane przy tworzeniu klucza. Zakres poprawny składniowo, ale nierozpoznany — literówka albo taki, którego żaden endpoint nie implementuje — jest odrzucany jako 422 API_KEY_VALIDATION_FAILED, z winowajcami w details.invalidScopes. Nie przyznajemy zakresów, które po cichu nic nie robią.
Zasada minimalnych uprawnień
Nadawaj tylko to, czego integracja naprawdę potrzebuje.
| Integracja | Zakresy |
|---|---|
| Dashboard tylko do odczytu | tasks.read, users.read, tags.read |
| Bot zakładający zadania | tasks.write, users.read (do wyszukania osoby), tags.read |
| Headless konfiguracja botów | bots.read, bots.write, locations.read, locations.write, phone-numbers.read, model-catalog.read, knowledge.* |
| Konsument webhooków | webhooks.manage (i webhook-payloads.read tylko jeśli naprawdę czytasz dostarczone treści) |
| Zlecanie połączeń z HIS/EDM | bot-calls.write, bot-calls.read |
| Pętla wsparcia | bot-calls.read, tickets.read, tickets.write |
| Diagnostyka telefonii | trunks.read, ivr-flows.read, queues.read |
| Administracja telefonią przez asystenta AI | trunks.write, ivr-flows.write, queues.write (odczyty są w nich zawarte) |
| Synchronizacja spraw z własnym systemem zgłoszeń | cases.write (odczyt jest w nim zawarty), users.read (do przypisania osoby) |