Uwierzytelnianie i klucze API

Jak żądania się uwierzytelniają

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." }'

Budowa klucza

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

• Prefiks: bk_{region}_ określa typ poświadczenia i jego region. Stały, charakterystyczny prefiks pozwala skanerom sekretów rozpoznać klucz Bird w kodzie, a segment regionu kieruje żądanie do właściwego hosta.
• Payload: 23 losowe znaki niosące 136 bitów entropii.
• Suma kontrolna: ostatnie 6 znaków to suma kontrolna reszty klucza, dzięki czemu SDK lub API mogą natychmiast odrzucić błędnie wpisany lub obcięty klucz, zanim zostanie w ogóle wyszukany.

Tworzenie klucza

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

• Zakresy są edytowalne. Edycja zastępuje zestaw uprawnień i zachowuje ten sam sekret. Możesz przyznać zakresy, które posiada twoje konto. Jeśli klucz został utworzony, zanim mógł obsługiwać uprawnienie takie jak voice, zrotuj go, aby dodać to uprawnienie. Unieważnionych kluczy i kluczy już zastąpionych przez rotację nie można edytować.
• Termin wygaśnięcia jest stały. Ustaw expires_at, gdy klucz powinien przestać działać w określonym momencie (zaangażowanie kontraktora, okno migracji). Po tym momencie klucz zwraca 401; klucz bez terminu wygaśnięcia działa do momentu unieważnienia.
• Zarządzanie kluczami pozostaje przy ludziach. Tworzenie, edytowanie i unieważnianie kluczy wymaga uprawnienia api_keys:write, posiadanego przez role administratora obszaru roboczego i developera (zobacz Użytkownicy, zespoły i role) i nigdy nienadalnego samemu kluczowi API. Wyciekły klucz nie może wygenerować kolejnych kluczy.

Zakresy i poziomy

Unieważnianie klucza

Rotacja klucza

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

1. Utwórz nowy klucz z tymi samymi zakresami.
2. Wdróż nowy klucz w swoich usługach.
3. Obserwuj last_used_on starego klucza, aż ruch się przeniesie.
4. Unieważnij stary klucz.

Klucze należą do obszaru roboczego

• Klucze przeżywają odejścia. Gdy pracownik odchodzi i jego konto użytkownika zostaje usunięte, utworzone przez niego klucze działają dalej. Nigdy nie masz awarii produkcyjnej z powodu odejścia osoby, która kliknęła "create". (Jej odejście to wciąż dobry powód, by zrotować klucze, do których miała dostęp.)
• Zasięg klucza kończy się na obszarze roboczym. Klucz nigdy nie może wykonywać operacji na poziomie organizacji: rozliczeń, zarządzania członkami organizacji, ustawień organizacji.

Ścieżka delegowana: tokeny OAuth dla CLI i serwera MCP

Następne kroki

• Dokumentacja uwierzytelniania: semantyka nagłówka żądania i odpowiedzi z błędami
• Regiony: hosty regionalne i routing
• Użytkownicy, zespoły i role: kto może zarządzać kluczami
• Obszar roboczy: obszar roboczy, do którego przypisany jest klucz