Autenticazione
Ogni richiesta API si autentica con una chiave API passata come bearer token nell'header Authorization:
curl https://us1.platform.bird.com/v1/email/messages \
-H "Authorization: Bearer bk_us1_Ab3xKq9mP2wR5tY8uI1oL4nJ..."Le chiavi sono limitate allo spazio di lavoro: una chiave si autentica come il tuo spazio di lavoro, include gli scope scelti al momento della creazione e può accedere solo alle risorse di quello spazio di lavoro. Come creare, definire gli scope, ruotare e revocare le chiavi è spiegato nella guida Autenticazione e chiavi API: creale nella dashboard in Platform tools > API keys, oppure senza browser con bird api-keys create. Questa pagina descrive il contratto a livello di protocollo.
Formato della chiave
Una chiave inizia con bk_{region}_, che indica la regione in cui è 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.
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 15 caratteri). Revoca e sostituisci una chiave persa.
Risposte di errore
Tutti gli errori usano la risposta di errore standard.
| Stato | Quando |
|---|---|
401 | L'header Authorization è mancante, la chiave è malformata o sconosciuta, oppure la chiave è stata revocata. |
403 | La chiave è valida ma non ha lo scope richiesto dall'endpoint. |
421 | La 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
- Guida Autenticazione e chiavi API: creare, definire gli scope, ruotare e revocare le chiavi
- URL di base e regioni: host regionali e modello di regione
- Errori: la risposta di errore e il catalogo
Risorse correlate
Continua con la documentazione, le guide e gli esempi per questo argomento.