Autoryzacja i tokeny

Publiczne API autoryzuje się personalnymi tokenami dostępu (PAT). Jeden token jest powiązany z kontem i działa na wszystkie Twoje encje konstruktora w granicach przyznanych zakresów dostępu.

Tworzenie tokenu

Personalny token tworzy się w panelu użytkownika, w sekcji tokenów personalnych. Wartość tokenu jest wyświetlana tylko raz podczas tworzenia — zapisz ją w bezpiecznym miejscu. Na serwerze token przechowywany jest wyłącznie w postaci zahashowanej i nie można go odtworzyć; w przypadku utraty — wygeneruj nowy i usuń stary.

Wszystkie tokeny personalne zaczynają się od prefiksu mbp_.

Przekazywanie tokenu

Token należy przekazywać w każdym żądaniu HTTP w nagłówku Authorization według schematu Bearer:

Authorization: Bearer mbp_TWÓJ_TOKEN

Ten sam nagłówek jest używany do dostępu sesyjnego z panelu webowego (tam jest to krótkotrwały JWT), jednak do integracji używaj właśnie tokenu personalnego mbp_….

Zakresy dostępu (scopes)

Token posiada zestaw zakresów dostępu w formacie zasób:akcja. Odczyt wymaga sufiksu :read, zmiany — :write. Dostępne zakresy:

  • bots:read, bots:write — boty, ich ustawienia, synchronizacja, token bota.
  • reactions:read, reactions:write — reakcje, import, testowanie formuł, powiązania, kolejność.
  • labels:read, labels:write — etykiety subskrybentów.
  • collections:read, collections:write — kolekcje i rekordy.
  • flows:read, flows:write — scenariusze.
  • integrations:read, integrations:write — integracje, połączenia, poświadczenia.
  • media:write — przesyłanie do biblioteki mediów.
  • templates:read, templates:write — szablony botów.
  • settings:read, settings:write — ustawienia.
  • subscribers:read — subskrybenci i historia dialogu (odczyt).
  • broadcasts:write — wysyłki masowe i zarządzanie nimi.
  • stats:read — statystyki i analityka.
  • billing:read — saldo i plany (odczyt).

Specjalny zakres * daje pełny dostęp do całego publicznego zestawu endpointów.

Co jest dostępne przez token, a co nie

Pod tokenem personalnym dostępne są wyłącznie endpointy konstruktora — te, które „pomagają budować bota". Niedostępne przez PAT (tylko z sesji webowej): logowanie i rejestracja, endpointy mobilne, płatności i doładowywanie salda, powiadomienia, dziennik audytu, operatorskie wysyłanie wiadomości do dialogu, przychodzące webhooki i callbacki płatnicze, WebSocket. Żądanie z tokenem mbp_ do takiej ścieżki zwróci 401 lub 403.

Jeśli token nie ma wymaganego zakresu dla danej ścieżki — zostanie zwrócony 403. Więcej o kodach błędów — w przewodniku po błędach.

Co dalej

  • Szybki start API — pierwsze zapytanie z tokenem.
  • Błędy — co oznaczają 401 i 403.
  • MCP — ten sam token dla interfejsu agentowego.