Authentifizierung & API-Keys

Wie sich Anfragen authentifizieren

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

Aufbau eines Keys

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

• Präfix: bk_{region}_ benennt den Credential-Typ und seine Region. Das feste, unverwechselbare Präfix ermöglicht es Secret-Scannern, einen Bird-Key im Code zu erkennen, und das Region-Segment leitet Ihre Anfrage an den richtigen Host.
• Payload: 23 zufällige Zeichen mit 136 Bit Entropie.
• Prüfsumme: Die letzten 6 Zeichen sind eine Prüfsumme des restlichen Keys. So kann ein SDK oder die API einen falsch eingegebenen oder abgeschnittenen Key sofort ablehnen, bevor er überhaupt nachgeschlagen wird.

Einen Key erstellen

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

• Scopes sind bearbeitbar. Beim Bearbeiten wird der Berechtigungssatz ersetzt und das gleiche Secret beibehalten. Sie können Scopes gewähren, die Ihr eigenes Konto besitzt. Wurde der Key erstellt, bevor er eine Berechtigung wie voice unterstützen konnte, rotieren Sie ihn, um diese Berechtigung hinzuzufügen. Widerrufene Keys und Keys, die bereits durch Rotation ersetzt wurden, können nicht bearbeitet werden.
• Das Ablaufdatum ist fest. Setzen Sie expires_at, wenn ein Key zu einem bekannten Zeitpunkt aufhören soll zu funktionieren (Engagement eines Auftragnehmers, Migrationsfenster). Nach diesem Zeitpunkt gibt der Key 401 zurück; ein Key ohne Ablaufdatum lebt, bis er widerrufen wird.
• Key-Verwaltung bleibt bei Personen. Das Erstellen, Bearbeiten und Widerrufen von Keys erfordert die api_keys:write-Berechtigung, die von den Workspace-Rollen Admin und Developer gehalten wird (siehe Benutzer, Teams & Rollen) und niemals einem API-Key selbst gewährt werden kann. Ein kompromittierter Key kann keine weiteren Keys erzeugen.

Scopes & Levels

Einen Key widerrufen

Einen Key rotieren

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

1. Erstellen Sie einen neuen Key mit denselben Scopes.
2. Deployen Sie den neuen Key in Ihren Diensten.
3. Beobachten Sie das last_used_on des alten Keys, bis der Traffic umgezogen ist.
4. Widerrufen Sie den alten Key.

Keys gehören zum Workspace

• Keys überleben Abgänge. Wenn ein Mitarbeiter das Unternehmen verlässt und sein Benutzerkonto entfernt wird, funktionieren die von ihm erstellten Keys weiterhin. Sie haben nie einen Produktionsausfall, weil die Person, die "create" geklickt hat, das Unternehmen verlassen hat. (Ihr Abgang ist dennoch ein guter Anlass, Keys zu rotieren, auf die sie Zugriff hatten.)
• Die Reichweite des Keys endet am Workspace. Er kann niemals Operationen auf Organisationsebene ausführen: Abrechnung, Org-Mitglieder, Org-Einstellungen.

Der delegierte Pfad: OAuth-Tokens für die CLI und den MCP-Server

Nächste Schritte

• Authentifizierungsreferenz: Header-Semantik und Fehlerantworten
• Regionen: Regionale Hosts und Routing
• Benutzer, Teams & Rollen: Wer Keys verwalten kann
• Workspace: Der Workspace, an den ein Key gebunden ist