Un invio programmato deve continuare a funzionare quando il dipendente che lo ha configurato lascia l'organizzazione. Uno strumento che agisce per conto di quel dipendente ha bisogno di un accesso che segua i suoi permessi.
Scegli la credenziale in base a questa titolarità. Tieni entrambe le credenziali fuori dal codice del browser e dai log, perché chiunque ne possieda una può tentare richieste autenticate.
Cosa mi permette di fare ciascuna credenziale?
Una chiave API agisce per conto di uno spazio di lavoro. Un token OAuth consente a uno strumento autorizzato di agire per conto di una persona.
Le chiavi Bird API iniziano con bk_. I loro permessi appartengono allo spazio di lavoro, quindi rimuovere il creatore non le invalida. Concedi solo gli scope necessari al servizio per limitare ciò che una chiave esposta può fare.
Una chiave non può eseguire operazioni a livello di organizzazione, come la gestione dei membri dell'organizzazione o la fatturazione. Aggiungere più scope dello spazio di lavoro non rimuove questo limite.
Quando accedi tramite il server CLI o MCP, autorizzi uno strumento con un sottoinsieme dei tuoi permessi. Lo strumento riceve un token bt_ di breve durata. Lo strumento gestisce il rinnovo del token, quindi non copiare quel token nel secret manager di un servizio.
Revoca uno strumento autorizzato tramite Profile > Connected apps. Usa l'autenticazione per scegliere gli scope e distinguere le chiavi dello spazio di lavoro dalle concessioni personali.
Come si esegue la rotazione di una chiave API?
Emetti un sostituto e distribuiscilo prima che termini la sovrapposizione della vecchia chiave.
Puoi eseguire la rotazione dalla dashboard, con bird api-keys rotate, o tramite lo strumento api_keys_rotate MCP. La rotazione CLI e MCP richiede una concessione personale con api_keys:write. Una chiave API non può avere quel permesso né eseguire la rotazione di un'altra chiave.
La rotazione restituisce il token del sostituto una sola volta. Salvalo immediatamente, perché letture successive non possono recuperarlo. Il sostituto mantiene il vecchio nome e le restrizioni IP. Mantiene anche i permessi, a meno che tu non fornisca nuovi scopes.
Imposta grace_period per controllare la sovrapposizione. Il valore predefinito è 24h, quindi completa il deploy entro quel giorno. Una scadenza precedente sulla vecchia chiave resta valida. La rotazione non la estende mai.
Usa grace_period: "0" quando una chiave trapelata deve essere revocata immediatamente. La validazione in cache può ancora accettarla per un breve periodo, come descritto di seguito.
- Richiedi la rotazione e salva il token restituito.
- Distribuisci il sostituto a ogni servizio prima che termini la sovrapposizione.
- Verifica le richieste riuscite con il sostituto attraverso i log del servizio.
- Lascia scadere la vecchia chiave oppure revocala quando il passaggio è completato.
Il riferimento alla rotazione descrive il comando e le sue opzioni.
Cosa può andare storto durante la rotazione?
Una risposta persa può lasciarti con un sostituto emesso il cui token non hai mai salvato.
Usa lo stesso Idempotency-Key quando riprovi la richiesta di rotazione, così Bird può riprodurre la sua risposta. Una chiave può essere ruotata una sola volta. Senza la stessa chiave di idempotenza, ripetere la rotazione restituisce 409. Esegui la rotazione del sostituto per una modifica pianificata successiva.
Una chiave revocata non può essere ruotata. Crea una nuova chiave se l'originale è già stata revocata.
Il sostituto non ha scadenza, anche quando l'originale ne aveva una. Non puoi aggiungere una scadenza in seguito. Crea una nuova chiave con expires_at quando deve smettere di funzionare a un momento noto.
Per un deploy di durata incerta, crea una seconda chiave e gestisci la sovrapposizione manualmente. Distribuiscila prima di revocare l'originale. Il periodo di grazia di una rotazione non può essere esteso dopo la richiesta.
Quanto velocemente ha effetto la revoca?
Una chiave revocata può continuare a essere accettata per un massimo di cinque secondi mentre la validazione in cache scade.
Considera una chiave esposta come utilizzabile per tutta quella finestra. La revoca è permanente, quindi una chiave revocata non può essere riattivata. Bird ne conserva il record per l'audit.
Usa key_prefix o fingerprint per identificare una chiave nelle conversazioni con il supporto. Non includere mai la credenziale completa, perché quegli identificatori sono sufficienti a distinguerla senza concedere accesso.
Quale credenziale scegliere?
Scegli in base a chi possiede il carico di lavoro e ai permessi di cui ha bisogno.
- Chiave API: un servizio che deve continuare a funzionare indipendentemente da chi lo ha creato.
- Concessione OAuth: un CLI o agente che agisce entro i permessi di una persona.
- Rotazione: una chiave sostitutiva che puoi distribuire durante una sovrapposizione nota.
- Nuova chiave con scadenza: una credenziale che deve smettere di funzionare a un momento specifico.
In breve
Le credenziali di servizio appartengono allo spazio di lavoro.
Una chiave sopravvive all'uscita di chi l'ha creata. Uno strumento che usa OAuth agisce entro i permessi della persona che lo ha autorizzato.
Esegui il deploy durante la sovrapposizione della rotazione.
La vecchia chiave continua a funzionare per 24 ore per impostazione predefinita, a meno che la sua scadenza esistente non arrivi prima.
Salva il sostituto quando viene emesso.
La rotazione restituisce il nuovo token una sola volta. Usa la stessa chiave di idempotenza se riprovi la richiesta di rotazione.
La revoca ha una breve finestra di propagazione.
La validazione in cache può accettare una chiave revocata per un massimo di cinque secondi: tieni conto di questo ritardo dopo una fuga di credenziali.