Zaplanowany nadawca powinien dalej działać, gdy pracownik, który go skonfigurował, odejdzie. Narzędzie działające w imieniu tego pracownika potrzebuje dostępu powiązanego z jego uprawnieniami.
Wybierz dane uwierzytelniające pod kątem tego, kto jest ich właścicielem. Nie umieszczaj żadnych danych uwierzytelniających w kodzie przeglądarki ani logach, bo każdy, kto je posiada, może próbować wysyłać uwierzytelnione żądania.
Co umożliwiają poszczególne dane uwierzytelniające?
Klucz API działa w imieniu obszaru roboczego. Token OAuth pozwala autoryzowanemu narzędziu działać w imieniu osoby.
Klucze Bird API zaczynają się od bk_. Ich uprawnienia należą do obszaru roboczego, więc usunięcie twórcy nie powoduje ich unieważnienia. Przyznaj tylko te zakresy, których usługa potrzebuje, żeby ograniczyć możliwości ujawnionego klucza.
Klucz nie może wykonywać operacji na poziomie organizacji, takich jak zarządzanie członkami organizacji czy rozliczeniami. Dodanie kolejnych zakresów obszaru roboczego nie znosi tego ograniczenia.
Logując się przez serwer CLI lub MCP, autoryzujesz narzędzie z podzbiorem swoich uprawnień. Narzędzie otrzymuje krótkotrwały token bt_. Samo zarządza odnawianiem tokenu, więc nie kopiuj go do menedżera sekretów usługi.
Unieważnij autoryzowane narzędzie w Profile > Connected apps. Użyj uwierzytelniania, aby wybrać zakresy i odróżnić klucze obszaru roboczego od osobistych uprawnień.
Jak przeprowadzić rotację klucza API?
Wydaj zamiennik i wdróż go, zanim skończy się okres nakładania się starego klucza.
Rotację możesz przeprowadzić z poziomu dashboardu, za pomocą bird api-keys rotate lub przez narzędzie api_keys_rotate MCP. Rotacja CLI i MCP wymaga osobistego uprawnienia z api_keys:write. Klucz API nie może posiadać tego uprawnienia ani przeprowadzać rotacji innego klucza.
Rotacja zwraca token zamiennika jednorazowo. Zapisz go natychmiast, bo późniejsze odczyty nie pozwolą go odzyskać. Zamiennik zachowuje starą nazwę i ograniczenia IP. Zachowuje też uprawnienia, chyba że podasz nowe scopes.
Ustaw grace_period, aby kontrolować okres nakładania się. Domyślna wartość to 24h, więc zakończ wdrożenie w ciągu tego dnia. Wcześniejsze wygaśnięcie starego klucza nadal obowiązuje. Rotacja nigdy go nie przedłuża.
Użyj grace_period: "0", gdy ujawniony klucz powinien zostać natychmiast unieważniony. Zbuforowana walidacja może go jeszcze przez chwilę akceptować, jak opisano poniżej.
- Zażądaj rotacji i zapisz zwrócony token.
- Wdróż zamiennik do każdej usługi przed końcem okresu nakładania się.
- Potwierdź w logach usługi, że żądania z zamiennikiem kończą się powodzeniem.
- Pozwól staremu kluczowi wygasnąć lub unieważnij go po zakończeniu przełączenia.
Dokumentacja rotacji opisuje polecenie i jego opcje.
Co może pójść nie tak podczas rotacji?
Utracona odpowiedź może sprawić, że otrzymasz wydany zamiennik, którego tokenu nigdy nie zapisałeś.
Używaj tego samego Idempotency-Key przy ponawianiu żądania rotacji, aby Bird mógł odtworzyć swoją odpowiedź. Klucz można poddać rotacji tylko raz. Bez tego samego klucza idempotentności powtórzenie rotacji zwraca 409. Przeprowadź rotację zamiennika przy kolejnej planowanej zmianie.
Unieważnionego klucza nie można poddać rotacji. Utwórz nowy klucz, jeśli oryginał został już unieważniony.
Zamiennik nie ma daty wygaśnięcia, nawet jeśli oryginał ją miał. Nie można dodać daty wygaśnięcia po utworzeniu. Utwórz nowy klucz z expires_at, gdy musi przestać działać w określonym czasie.
W przypadku wdrożenia o nieokreślonym czasie trwania utwórz drugi klucz i sam zarządzaj okresem nakładania się. Wdróż go przed unieważnieniem oryginału. Okresu karencji rotacji nie można wydłużyć po wysłaniu żądania.
Jak szybko zaczyna obowiązywać unieważnienie?
Unieważniony klucz może być nadal akceptowany przez maksymalnie pięć sekund, dopóki nie wygaśnie zbuforowana walidacja.
Traktuj ujawniony klucz jako użyteczny przez całe to okno. Unieważnienie jest trwałe, więc unieważnionego klucza nie można ponownie aktywować. Bird przechowuje jego rekord na potrzeby audytu.
Użyj key_prefix lub fingerprint, aby zidentyfikować klucz w rozmowach z pomocą techniczną. Nigdy nie podawaj pełnych danych uwierzytelniających, bo te identyfikatory wystarczą do rozróżnienia klucza bez przyznawania dostępu.
Które dane uwierzytelniające wybrać?
Wybierz na podstawie tego, kto jest właścicielem obciążenia i jakich uprawnień ono wymaga.
- Klucz API: usługa, która powinna działać niezależnie od osoby, która ją utworzyła.
- Uprawnienie OAuth: CLI lub agent działający w ramach uprawnień osoby.
- Rotacja: klucz zastępczy, który możesz wdrożyć w znanym okresie nakładania się.
- Nowy klucz z datą wygaśnięcia: dane uwierzytelniające, które muszą przestać działać w określonym czasie.
W skrócie
Dane uwierzytelniające usługi należą do obszaru roboczego.
Klucz przetrwa odejście osoby, która go utworzyła. Narzędzie korzystające z OAuth działa w ramach uprawnień osoby, która je autoryzowała.
Wdrażaj w trakcie okresu nakładania się rotacji.
Stary klucz domyślnie działa jeszcze przez 24 godziny, chyba że wcześniejsze wygaśnięcie nastąpi szybciej.
Zapisz zamiennik w momencie jego wydania.
Rotacja zwraca nowy token jednorazowo. Używaj tego samego klucza idempotentności, jeśli ponawiasz żądanie rotacji.
Unieważnienie ma krótkie okno propagacji.
Zbuforowana walidacja może zaakceptować unieważniony klucz przez maksymalnie pięć sekund, więc uwzględnij to opóźnienie po wycieku.