Uwierzytelnianie

Każde żądanie API uwierzytelnia się kluczem API przekazywanym jako token bearer w nagłówku Authorization:

Przykład kodu

curl https://us1.platform.bird.com/v1/email/messages \
  -H "Authorization: Bearer bk_us1_Ab3xKq9mP2wR5tY8uI1oL4nJ..."

Klucze działają w zakresie obszaru roboczego: klucz uwierzytelnia się jako Twój obszar roboczy, posiada uprawnienia wybrane przy tworzeniu i daje dostęp wyłącznie do jego zasobów. Tworzenie, nadawanie uprawnień, rotacja i unieważnianie kluczy są opisane w Przewodniku po uwierzytelnianiu i kluczach API: twórz je w dashboardzie w sekcji Developers > Klucze API lub bez przeglądarki za pomocą bird api-keys create. Ta strona opisuje kontrakt na poziomie protokołu.

Format klucza

Przykład kodu

bk_us1_Ab3xKq9mP2wR5tY8uI1oL4nJ...
└┬┘└┬┘ └──────────┬──────────┘└┬┘
 │  │          payload      checksum
 │  └ region (routes the request)
 └ Bird key prefix

Klucz składa się z bk_{region}_{payload}{checksum}:

bk_{region}_: Prefiks identyfikuje typ poświadczenia oraz region, w którym klucz został utworzony. Klucze bk_us1_ działają tylko z https://us1.platform.bird.com, a klucze bk_eu1_ tylko z https://eu1.platform.bird.com. Oficjalne SDK i CLI używają tego prefiksu do wyboru hosta. Stały prefiks bk_ jest zarejestrowany w GitHub secret scanning, więc klucz Bird ujawniony w publicznym repozytorium zostanie wykryty i zgłoszony.
Payload: Długi losowy ciąg znaków o entropii co najmniej 128 bitów.
Checksum: Ostatnie 6 znaków to suma kontrolna reszty klucza, dzięki czemu klient może lokalnie odrzucić błędnie wpisany lub ucięty klucz, zanim wyśle jakiekolwiek żądanie.

Pełny klucz jest zwracany dokładnie raz, w odpowiedzi, która go tworzy. Tekstu jawnego nie można pobrać ponownie, a dashboard pokazuje jedynie skrócony key_prefix (pierwsze 12 znaków). Unieważnij i zastąp utracony klucz.

Odpowiedzi w przypadku błędów

Wszystkie błędy używają standardowej odpowiedzi z błędem.

Status	Kiedy
401	Brakuje nagłówka Authorization, klucz jest nieprawidłowy lub nieznany albo został unieważniony.
403	Klucz jest prawidłowy, ale nie posiada uprawnienia wymaganego przez endpoint.
421	Region klucza nie pasuje do hosta, np. klucz bk_eu1_... wysłany do us1.platform.bird.com.

Treść 421 Misdirected Request (typ błędu misdirected_error, kod E01010) zawiera nazwę prawidłowego hosta regionalnego, dzięki czemu klient może wykryć pomyłkę i wysłać żądanie ponownie bez zgadywania. Zobacz Bazowe adresy URL i regiony.

Sesje dashboardu to nie klucze API

Dashboard Bird nie używa kluczy API: osoba logująca się otrzymuje ciasteczko sesyjne powiązane z jej własnymi uprawnieniami użytkownika. Ciasteczka sesyjne nie są akceptowane na programatycznej powierzchni API, a klucze API nie są akceptowane przez dashboard. Obciążenia serwerowe zawsze używają kluczy API.

Powiązane

Przewodnik po uwierzytelnianiu i kluczach API: tworzenie, nadawanie uprawnień, rotacja i unieważnianie kluczy
Bazowe adresy URL i regiony: hosty regionalne i model regionów
Błędy: odpowiedź z błędem i katalog

Powiązane zasoby

Kontynuuj z dokumentacją, przewodnikami i przykładami dotyczącymi tego tematu. Zasoby są w języku angielskim.

Zrozum koncepcjęShould I use a Bird SDK or call the API directly?Podążaj ścieżką naukiBuild your first integration Przewodnik wdrożeniowySend your first email

Uzyskaj brief wdrożeniowy