Autentikasi & kunci API

Cara permintaan melakukan autentikasi

import { BirdClient } from "@messagebird/sdk";

const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });

await bird.email.send({
  from: "hello@yourdomain.com",
  to: ["delivered@messagebird.dev"],
  subject: "Hi",
  text: "Hello.",
});

import os

from bird import Bird

client = Bird(api_key=os.environ["BIRD_API_KEY"])

client.email.send(
    from_="hello@yourdomain.com",
    to=["delivered@messagebird.dev"],
    subject="Hi",
    text="Hello.",
)

client, err := bird.NewClient(option.WithAPIKey(os.Getenv("BIRD_API_KEY")))
if err != nil {
	log.Fatal(err)
}

_, err = client.Email.Send(context.Background(), bird.EmailSendParams{
	From:    "hello@yourdomain.com",
	To:      []string{"delivered@messagebird.dev"},
	Subject: "Hi",
	Text:    "Hello.",
})

use MessageBird\Bird;

$bird = new Bird(getenv('BIRD_API_KEY') ?: '');

$bird->email->send(
    from: 'hello@yourdomain.com',
    to: ['delivered@messagebird.dev'],
    subject: 'Hi',
    text: 'Hello.',
);

export BIRD_API_KEY="bk_us1_..."

bird email send \
  --from hello@yourdomain.com \
  --to delivered@messagebird.dev \
  --subject Hi \
  --text Hello.

curl -X POST https://us1.platform.bird.com/v1/email/messages \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "from": "hello@yourdomain.com", "to": ["delivered@messagebird.dev"], "subject": "Hi", "text": "Hello." }'

Anatomi kunci

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

• Prefix: bk_{region}_ menamai tipe kredensial dan regionnya. Prefix tetap yang khas inilah yang memungkinkan pemindai rahasia mengenali kunci Bird dalam kode, dan segmen region mengarahkan permintaan Anda ke host yang tepat.
• Payload: 23 karakter acak yang membawa 136 bit entropi.
• Checksum: 6 karakter terakhir adalah checksum dari sisa kunci, sehingga SDK atau API dapat langsung menolak kunci yang salah ketik atau terpotong, sebelum kunci tersebut pernah dicari.

Membuat kunci

bird auth login --scope api_keys:write
bird api-keys create --body-file - <<'JSON'
{
  "name": "Email operations production key",
  "scopes": [{ "scope": "emails", "level": "write" }]
}
JSON

• Scope dapat diedit. Pengeditan mengganti set izin dan mempertahankan rahasia yang sama. Anda dapat memberikan scope yang dimiliki akun Anda sendiri. Jika kunci dibuat sebelum bisa mendukung izin seperti voice, rotasi kunci tersebut untuk menambahkan izin itu. Kunci yang dicabut dan kunci yang sudah digantikan oleh rotasi tidak dapat diedit.
• Kedaluwarsa bersifat tetap. Atur expires_at ketika kunci harus berhenti bekerja pada waktu tertentu (keterlibatan kontraktor, jendela migrasi). Setelah momen tersebut, kunci mengembalikan 401; kunci tanpa kedaluwarsa berlaku sampai dicabut.
• Pengelolaan kunci tetap pada orang. Membuat, mengedit, dan mencabut kunci memerlukan izin api_keys:write, yang dimiliki oleh peran workspace admin dan developer (lihat Users, teams & roles) dan tidak pernah dapat diberikan ke kunci API itu sendiri. Kunci yang bocor tidak dapat membuat lebih banyak kunci.

Scope & level

Mencabut kunci

Merotasi kunci

bird auth login --scope api_keys:write
bird api-keys rotate key_01hqz8kp3v9x2m --yes

1. Buat kunci baru dengan scope yang sama.
2. Deploy kunci baru ke layanan Anda.
3. Pantau last_used_on kunci lama sampai lalu lintas berpindah.
4. Cabut kunci lama.

Kunci terikat pada workspace

• Kunci tetap bertahan saat seseorang pergi. Ketika seorang karyawan keluar dan akun penggunanya dihapus, kunci yang mereka buat tetap bekerja. Anda tidak pernah mengalami gangguan produksi karena orang yang mengklik "create" meninggalkan perusahaan. (Kepergian mereka tetap merupakan saat yang tepat untuk merotasi kunci yang pernah mereka akses.)
• Jangkauan kunci berhenti di workspace. Kunci tidak pernah dapat menjalankan operasi level organisasi: penagihan, anggota organisasi, pengaturan organisasi.

Jalur terdelegasi: token OAuth untuk CLI dan server MCP

Langkah selanjutnya

• Referensi autentikasi: semantik header permintaan dan respons kesalahan
• Region: host regional dan routing
• Users, teams & roles: siapa yang dapat mengelola kunci
• Workspace: workspace tempat kunci terikat