Sign inGet Started
Inizia ora
Guide
Riferimento API
SDK
CLI
Knowledge Base
Changelog

Autenticazione

Ogni richiesta API si autentica con una chiave API passata come bearer token nell'header Authorization:
Esempio di codice
curl https://us1.platform.bird.com/v1/email/messages \
  -H "Authorization: Bearer bk_us1_Ab3xKq9mP2wR5tY8uI1oL4nJ..."
Le chiavi hanno ambito di spazio di lavoro: una chiave si autentica come il tuo spazio di lavoro, porta gli scope scelti alla creazione e può raggiungere solo le sue risorse. Come creare, definire gli scope, ruotare e revocare le chiavi è descritto nella guida Autenticazione e chiavi API: creale nella dashboard sotto Developers > Chiavi API, oppure senza browser con bird api-keys create. Questa pagina tratta il contratto a livello di protocollo.

Formato della chiave

Esempio di codice
bk_us1_Ab3xKq9mP2wR5tY8uI1oL4nJ...
└┬┘└┬┘ └──────────┬──────────┘└┬┘
 │  │          payload      checksum
 │  └ region (routes the request)
 └ Bird key prefix
Una chiave è bk_{region}_{payload}{checksum}:
  • bk_{region}_: Il prefisso identifica il tipo di credenziale e la regione in cui la chiave è stata creata. Le chiavi bk_us1_ sono valide solo verso https://us1.platform.bird.com, e le chiavi bk_eu1_ solo verso https://eu1.platform.bird.com. Gli SDK ufficiali e il CLI usano questo prefisso per selezionare l'host. Il prefisso fisso bk_ è registrato con GitHub secret scanning, quindi una chiave Bird esposta in un repository pubblico viene rilevata e segnalata.
  • Payload: Una lunga stringa casuale con almeno 128 bit di entropia.
  • Checksum: Gli ultimi 6 caratteri sono un checksum del resto della chiave, che permette al client di rifiutare localmente una chiave digitata male o troncata prima di qualsiasi richiesta.
La chiave completa viene restituita una sola volta, nella risposta che la crea. Il testo in chiaro non può essere recuperato di nuovo e la dashboard mostra solo un breve key_prefix (i primi 12 caratteri). Revoca e sostituisci una chiave persa.

Risposte di errore

Tutti gli errori usano la risposta di errore standard.
StatoQuando
401L'header Authorization è mancante, la chiave è malformata o sconosciuta, oppure la chiave è stata revocata.
403La chiave è valida ma non ha lo scope richiesto dall'endpoint.
421La regione della chiave non corrisponde all'host, ad esempio una chiave bk_eu1_... inviata a us1.platform.bird.com.
Il corpo 421 Misdirected Request (tipo di errore misdirected_error, codice E01010) indica l'host regionale corretto, così il client può rilevare l'errore e reinviare la richiesta senza tentativi alla cieca. Vedi URL di base e regioni.

Le sessioni della dashboard non sono chiavi API

La dashboard Bird non usa chiavi API: una persona che effettua il login ottiene un cookie di sessione, limitato ai propri permessi utente. I cookie di sessione non sono accettati sulla superficie programmatica API, e le chiavi API non sono accettate dalla dashboard. I carichi di lavoro server usano sempre chiavi API.

Correlati

Risorse correlate

Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.

Comprendi il concettoShould I use a Bird SDK or call the API directly?Segui il percorso di apprendimentoBuild your first integrationGuida all'implementazioneSend your first email
Ottieni un brief di implementazione