Een geplande verzender moet blijven werken als de medewerker die hem heeft ingesteld, vertrekt. Een tool die namens die medewerker handelt, heeft toegang nodig die de rechten van die persoon volgt.
Kies het inlogmiddel op basis van dat eigenaarschap. Houd beide typen inloggegevens uit browsercode en logs, want iedereen die ze heeft kan geauthenticeerde verzoeken doen.
Wat kan ik met elk inlogmiddel doen?
Een API-key handelt namens een werkruimte. Een OAuth-token laat een geautoriseerde tool namens een persoon handelen.
Bird API-keys beginnen met bk_. De rechten ervan horen bij de werkruimte, dus het verwijderen van de maker maakt ze niet ongeldig. Ken alleen de scopes toe die de service nodig heeft, zodat een blootgestelde key beperkt is in wat hij kan doen.
Een key kan geen bewerkingen op organisatieniveau uitvoeren, zoals het beheren van organisatieleden of facturering. Meer werkruimte-scopes toevoegen heft die grens niet op.
Wanneer je je aanmeldt via de CLI- of MCP-server, autoriseer je een tool met een subset van je rechten. De tool ontvangt een kortlopend bt_-token. De tool regelt tokenvernieuwing, dus kopieer dat token niet naar de secret manager van een service.
Trek een geautoriseerde tool in via Profile > Connected apps. Gebruik authenticatie om scopes te kiezen en werkruimte-keys van persoonlijke toekenningen te onderscheiden.
Hoe roteer ik een API-key?
Geef een vervanging uit en rol deze uit voordat de overlap van de oude key eindigt.
Je kunt roteren vanuit het dashboard, met bird api-keys rotate, of via de api_keys_rotate MCP-tool. CLI- en MCP-rotatie vereisen een persoonlijke toekenning met api_keys:write. Een API-key kan die rechten niet hebben en kan geen andere key roteren.
Rotatie geeft het token van de vervanging één keer terug. Sla het direct op, want latere uitlezingen kunnen het niet herstellen. De vervanging behoudt de oude naam en IP-beperkingen. Ook de rechten blijven behouden, tenzij je nieuwe scopes meegeeft.
Stel grace_period in om de overlap te bepalen. De standaardwaarde is 24h, dus rond de uitrol binnen die dag af. Een eerdere vervaldatum op de oude key geldt nog steeds. Rotatie verlengt die nooit.
Gebruik grace_period: "0" wanneer een gelekte key direct moet worden ingetrokken. Gecachte validatie kan de key nog kort accepteren, zoals hieronder beschreven.
- Vraag rotatie aan en sla het teruggegeven token op.
- Rol de vervanging uit naar elke service voordat de overlap eindigt.
- Bevestig geslaagde verzoeken met de vervanging via de servicelogs.
- Laat de oude key verlopen, of trek hem in wanneer de overstap is voltooid.
De rotatiereferentie beschrijft het commando en de opties.
Wat kan er misgaan tijdens rotatie?
Een verloren antwoord kan ertoe leiden dat je een uitgegeven vervanging hebt waarvan je het token nooit hebt opgeslagen.
Gebruik dezelfde Idempotency-Key wanneer je het rotatieverzoek opnieuw probeert, zodat Bird het antwoord kan herhalen. Een key kan maar één keer worden geroteerd. Zonder dezelfde idempotency-key geeft herhaling van de rotatie 409 terug. Roteer de vervanging voor een latere geplande wijziging.
Een ingetrokken key kan niet worden geroteerd. Maak een nieuwe key aan als de originele al is ingetrokken.
De vervanging heeft geen vervaldatum, ook niet als de originele die had. Je kunt achteraf geen vervaldatum toevoegen. Maak een nieuwe key aan met expires_at als hij op een bekend moment moet stoppen met werken.
Maak voor een uitrol met een onzekere duur een tweede key aan en beheer de overlap zelf. Rol de nieuwe key uit voordat je de originele intrekt. De overgangsperiode van een rotatie kan na het verzoek niet worden verlengd.
Hoe snel wordt intrekking van kracht?
Een ingetrokken key kan tot vijf seconden geaccepteerd blijven terwijl gecachte validatie verloopt.
Beschouw een blootgestelde key als bruikbaar gedurende dat venster. Intrekking is permanent, dus een ingetrokken key kan niet opnieuw worden geactiveerd. Bird bewaart de registratie voor audit.
Gebruik key_prefix of fingerprint om een key te identificeren in supportgesprekken. Vermeld nooit het volledige inlogmiddel, want die identifiers zijn voldoende om de key te herkennen zonder toegang te verlenen.
Welk inlogmiddel moet ik kiezen?
Kies op basis van wie eigenaar is van de workload en welke rechten deze nodig heeft.
- API-key: een service die onafhankelijk van de maker moet blijven werken.
- OAuth-toekenning: een CLI of agent die handelt binnen de rechten van een persoon.
- Rotatie: een vervangende key die je kunt uitrollen tijdens een bekende overlap.
- Nieuwe key met vervaldatum: een inlogmiddel dat op een specifiek moment moet stoppen met werken.
Kort gezegd
Service-inloggegevens horen bij de werkruimte.
Een key blijft bestaan als de maker vertrekt. Een tool die OAuth gebruikt, handelt binnen de rechten van de persoon die de tool geautoriseerd heeft.
Rol uit tijdens de rotatie-overlap.
De oude key blijft standaard 24 uur werken, tenzij de bestaande vervaldatum eerder valt.
Sla de vervanging op zodra deze is uitgegeven.
Rotatie geeft het nieuwe token één keer terug. Gebruik dezelfde idempotency-key als je het rotatieverzoek opnieuw probeert.
Intrekking heeft een kort propagatievenster.
Gecachte validatie kan een ingetrokken key tot vijf seconden accepteren, dus houd rekening met die vertraging na een lek.