Authenticatie & API-keys

Hoe verzoeken authenticeren

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

Opbouw van een key

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

• Prefix: bk_{region}_ benoemt het credentialtype en de regio. Het vaste, herkenbare prefix is wat secret scanners in staat stelt een Bird-key in code te herkennen, en het regiosegment routeert je verzoek naar de juiste host.
• Payload: 23 willekeurige tekens met 136 bits aan entropie.
• Checksum: de laatste 6 tekens zijn een checksum van de rest van de key, zodat een SDK of de API een verkeerd getypte of afgekapte key direct kan afwijzen, voordat deze ooit wordt opgezocht.

Een key aanmaken

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 zijn bewerkbaar. Bewerken vervangt de machtigingenset en behoudt hetzelfde geheim. Je kunt scopes toekennen die je eigen account heeft. Als de key is aangemaakt voordat deze een machtiging zoals voice kon ondersteunen, roteer hem dan om die machtiging toe te voegen. Ingetrokken keys en keys die al door rotatie zijn vervangen, kunnen niet worden bewerkt.
• De verloopdatum staat vast. Stel expires_at in wanneer een key op een bekend tijdstip moet stoppen met werken (de opdracht van een contractant, een migratieperiode). Na dat moment retourneert de key 401; een key zonder verloopdatum blijft geldig tot hij wordt ingetrokken.
• Keybeheer blijft bij mensen. Het aanmaken, bewerken en intrekken van keys vereist de api_keys:write-machtiging, die de werkruimte-admin- en developer-rollen hebben (zie Users, teams & roles) en die nooit aan een API-key zelf kan worden toegekend. Een gelekte key kan geen nieuwe keys aanmaken.

Scopes & niveaus

Een key intrekken

Een key roteren

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

1. Maak een nieuwe key aan met dezelfde scopes.
2. Deploy de nieuwe key naar je services.
3. Houd de last_used_on van de oude key in de gaten totdat het verkeer is verplaatst.
4. Trek de oude key in.

Keys horen bij de werkruimte

• Keys overleven vertrekken. Wanneer een medewerker vertrekt en het gebruikersaccount wordt verwijderd, blijven de keys die diegene heeft aangemaakt werken. Je hebt nooit een productie-uitval omdat de persoon die op "create" klikte het bedrijf heeft verlaten. (Het vertrek is wel een goed moment om keys te roteren waartoe diegene toegang had.)
• Het bereik van de key stopt bij de werkruimte. De key kan nooit bewerkingen op organisatieniveau uitvoeren: facturering, organisatieleden, organisatie-instellingen.

Het gedelegeerde pad: OAuth-tokens voor de CLI en MCP-server

Volgende stappen

• Authenticatiereferentie: headersemantiek en foutantwoorden voor verzoeken
• Regions: regionale hosts en routering
• Users, teams & roles: wie keys kan beheren
• Workspace: de werkruimte waaraan een key is gebonden