Uwierzytelnianie
Każde żądanie API uwierzytelnia się kluczem API przekazywanym jako token bearer w nagłówku Authorization:
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 Platform tools > API keys lub bez przeglądarki za pomocą bird api-keys create. Ta strona opisuje kontrakt na poziomie protokołu.
Format klucza
Klucz zaczyna się od bk_{region}_, co wskazuje region, w którym 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.
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 15 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
Przejdź do dokumentacji, przewodników i przykładów dotyczących tego tematu.