Uwierzytelnianie
Token bearer
Wysyłaj Authorization: Bearer sk_live_… w każdym żądaniu. Nigdy nie umieszczaj klucza w adresie URL ani w ciasteczku; nie ma na to innego nagłówka. Brakujący, źle sformatowany, unieważniony lub wygasły klucz odpowiada 401 unauthorized, bez wskazania który.
Klucz należy do jednego obszaru roboczego. GET /v1/workspaces/current zwraca go wraz z planem. Jeśli wyślesz X-Workspace-Id, musi wskazywać obszar roboczy klucza.
Tworzenie kluczy
Twórz klucze w aplikacji w Settings → API. Editorzy, administratorzy i właściciel tworzą klucze działające jako oni sami; administratorzy mogą też zmieniać nazwy i unieważniać klucze dowolnej osoby. Przeglądający nie mogą tworzyć kluczy. Obszar roboczy może mieć 50 aktywnych kluczy.
Sekret jest pokazywany raz, a my przechowujemy tylko jego hash. API nie dopuszcza wywołań z przeglądarki między źródłami: trzymaj klucze na swoim serwerze.
Zakresy
Wybierz zakresy przy tworzeniu klucza; nie można ich zmienić później (obróć klucz lub utwórz nowy). Żądanie wymaga zakresu trasy, podanego przy każdej trasie w dokumentacji API. Klucz bez niego dostaje 403 forbidden z details.reason missing_scope.
codes:readLista i odczyt kodów, ich wersji i aktywności; pobieranie plików; uruchamianie i odczyt eksportów oraz zadań zbiorczych.Viewer lub wyżejcodes:writeTworzenie, zmiana, wstrzymywanie, przenoszenie i usuwanie kodów; tworzenie zbiorcze; przesyłanie logo i plików.Editor lub wyżejanalytics:readStatystyki obszaru roboczego i poszczególnych kodów oraz rekordy każdego skanu.Viewer lub wyżejsubmissions:readOdpowiedzi na formularze hostowane. Zawierają dane osobowe respondentów.Editor lub wyżejfolders:readLista i odczyt folderów.Viewer lub wyżejfolders:writeTworzenie, zmiana nazwy, przenoszenie i usuwanie folderów. Udostępnianie zostaje w aplikacji.Editor lub wyżejtemplates:readLista i odczyt szablonów wyglądu.Viewer lub wyżejtemplates:writeTworzenie, zmiana i usuwanie szablonów wyglądu.Editor lub wyżejdomains:readLista własnych domen i ich statusu, aby wybrać jedną dla nowych kodów.Viewer lub wyżejwebhooks:readLista endpointów webhooków i ich dostarczeń.Administrator lub wyżejwebhooks:writeRejestrowanie, zmiana i usuwanie endpointów webhooków; wysyłanie zdarzenia testowego; ponowne dostarczanie. Tylko dla administratorów.Administrator lub wyżejtags:readLista tagów obszaru roboczego i liczby kodów z każdym tagiem.Viewer lub wyżejtags:writeTworzenie, zmiana nazwy i koloru oraz usuwanie tagów. Tagowanie kodów wymaga Codes · write.Editor lub wyżejcards:readLista i odczyt wizytówek zespołu i ich statystyk.Viewer lub wyżejcards:writeTworzenie, zmiana, dezaktywacja i przepisywanie wizytówek. Tylko dla administratorów.Administrator lub wyżejconversions:writeWysyłanie konwersji ze swojego serwera (zamówienia, rejestracje) do lejka skanów.Editor lub wyżejRole
Klucz nigdy nie robi więcej, niż pozwala bieżąca rola jego twórcy, maksymalnie jako Editor. Jeśli twórca zostanie zdegradowany do przeglądającego, klucz od razu traci zakresy zapisu; gdy twórca opuści obszar roboczy, jego klucze są unieważniane.
webhooks:read i webhooks:write są wyjątkiem: mogą je nadać tylko administratorzy i właściciel, a działają tylko dopóki twórca jest nadal administratorem.
Ograniczenia folderów i IP
Klucz można ograniczyć do maksymalnie 20 folderów i ich podfolderów, na przykład jeden klucz na folder klienta. Wtedy nie widzi niczego poza nimi, a zapis gdzie indziej odpowiada 403 z details.reason api_key_folder_restricted.
Klucz można też ograniczyć do maksymalnie 20 zakresów IP w postaci CIDR (203.0.113.0/24). Wywołanie z innego miejsca odpowiada 403 z details.reason ip_not_allowed.
Wygaśnięcie i rotacja
Klucz może wygasnąć w wybranym dniu. Rotacja klucza wydaje nowy sekret z tą samą nazwą, zakresami i ograniczeniami; stary sekret działa domyślnie przez 24 godz. (od 0 do 168), aby można było wdrożyć nowy bez przestoju. Unieważnienie działa natychmiast.
Czego klucz nie może
Klucze wywołują tylko trasy z dokumentacji API. Twoje konto, członkowie i zaproszenia, rozliczenia, ustawienia obszaru roboczego, udostępnianie, konfiguracja domen i same klucze API zostają w aplikacji: te trasy odpowiadają kluczowi 403 forbidden z details.reason session_required.