Autentikasi

Setiap permintaan API diautentikasi dengan kunci API yang dikirim sebagai bearer token di header Authorization:

Contoh kode

curl https://us1.platform.bird.com/v1/email/messages \
  -H "Authorization: Bearer bk_us1_Ab3xKq9mP2wR5tY8uI1oL4nJ..."

Kunci dicakupkan ke workspace: sebuah kunci mengautentikasi sebagai workspace Anda, membawa cakupan yang dipilih saat pembuatan, dan hanya dapat mengakses resource miliknya. Cara membuat, mencakupkan, merotasi, dan mencabut kunci dibahas di Panduan autentikasi & kunci API: buat kunci di dashboard pada Developers > Kunci API, atau tanpa browser dengan bird api-keys create. Halaman ini membahas kontrak tingkat protokol.

Format kunci

Contoh kode

bk_us1_Ab3xKq9mP2wR5tY8uI1oL4nJ...
└┬┘└┬┘ └──────────┬──────────┘└┬┘
 │  │          payload      checksum
 │  └ region (routes the request)
 └ Bird key prefix

Sebuah kunci terdiri dari bk_{region}_{payload}{checksum}:

bk_{region}_: Prefiks mengidentifikasi tipe kredensial dan region tempat kunci dibuat. Kunci bk_us1_ hanya berlaku terhadap https://us1.platform.bird.com, dan kunci bk_eu1_ hanya terhadap https://eu1.platform.bird.com. SDK resmi dan CLI menggunakan prefiks ini untuk memilih host. Prefiks tetap bk_ terdaftar di GitHub secret scanning, sehingga kunci Bird yang bocor di repositori publik terdeteksi dan dilaporkan.
Payload: String acak panjang dengan entropi 128+ bit.
Checksum: 6 karakter terakhir adalah checksum dari sisa kunci, sehingga klien dapat menolak kunci yang salah ketik atau terpotong secara lokal sebelum permintaan dikirim.

Kunci lengkap dikembalikan tepat satu kali, dalam respons yang membuatnya. Teks asli tidak dapat diambil lagi, dan dashboard hanya menampilkan key_prefix singkat (12 karakter pertama). Cabut dan ganti kunci yang hilang.

Respons kegagalan

Semua kegagalan menggunakan respons kesalahan standar.

Status	Kapan
401	Header Authorization tidak ada, kunci salah format atau tidak dikenal, atau kunci telah dicabut.
403	Kunci valid tetapi tidak memiliki cakupan yang dibutuhkan endpoint.
421	Region kunci tidak cocok dengan host, misalnya kunci bk_eu1_... dikirim ke us1.platform.bird.com.

Body 421 Misdirected Request (tipe error misdirected_error, kode E01010) menyebutkan host regional yang benar, sehingga klien dapat mendeteksi kesalahan dan mengirim ulang tanpa menebak. Lihat URL dasar dan region.

Sesi dashboard bukan kunci API

Dashboard Bird tidak menggunakan kunci API: pengguna yang login mendapatkan cookie sesi, dicakupkan ke izin pengguna mereka sendiri. Cookie sesi tidak diterima di permukaan API programatik, dan kunci API tidak diterima oleh dashboard. Beban kerja server selalu menggunakan kunci API.

Terkait

Panduan autentikasi & kunci API: membuat, mencakupkan, merotasi, dan mencabut kunci
URL dasar dan region: host regional dan model region
Error: respons kesalahan dan katalog

Sumber daya terkait

Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini. Sumber daya tersedia dalam bahasa Inggris.

Pahami konsepnyaShould I use a Bird SDK or call the API directly?Ikuti jalur pembelajaranBuild your first integration Panduan implementasiSend your first email

Dapatkan ringkasan implementasi