Authentication और API keys

अनुरोध कैसे authenticate होते हैं

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

Key की संरचना

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

• Prefix: bk_{region}_ क्रेडेंशियल का प्रकार और उसका region बताता है। यह निश्चित, विशिष्ट prefix ही है जो secret scanners को कोड में Bird key पहचानने देता है, और region सेगमेंट आपके अनुरोध को सही host पर रूट करता है।
• Payload: 136 बिट की entropy वाले 23 रैंडम कैरेक्टर।
• Checksum: अंतिम 6 कैरेक्टर बाकी key का checksum हैं, ताकि कोई SDK या API गलत टाइप की गई या कटी हुई key को lookup से पहले ही तुरंत अस्वीकार कर सके।

Key बनाना

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 संपादन योग्य हैं। संपादन permission set को बदल देता है और वही secret रखता है। आप वे scopes grant कर सकते हैं जो आपके अपने अकाउंट में हैं। अगर key ऐसी permission को सपोर्ट करने से पहले बनाई गई थी जैसे voice, तो वह permission जोड़ने के लिए इसे rotate करें। Revoked keys और rotation द्वारा पहले से बदली गई keys को संपादित नहीं किया जा सकता।
• Expiry निश्चित है। expires_at तब सेट करें जब key को किसी ज्ञात समय पर काम करना बंद करना हो (किसी ठेकेदार का कार्यकाल, माइग्रेशन विंडो)। उस क्षण के बाद key 401 लौटाती है; बिना expiry वाली key revoke होने तक काम करती रहती है।
• Key प्रबंधन लोगों के पास रहता है। Keys बनाने, संपादित करने और revoke करने के लिए api_keys:write permission चाहिए, जो workspace admin और developer roles के पास होती है (देखें Users, teams & roles) और किसी API key को कभी grant नहीं की जा सकती। लीक हुई key और keys नहीं बना सकती।

Scopes और levels

Key revoke करना

Key rotate करना

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

1. समान scopes के साथ एक नई key बनाएँ।
2. नई key को अपनी सेवाओं में deploy करें।
3. ट्रैफ़िक स्थानांतरित होने तक पुरानी key का last_used_on देखें।
4. पुरानी key revoke करें।

Keys वर्कस्पेस की होती हैं

• Keys कर्मचारी के जाने पर भी चलती रहती हैं। जब कोई कर्मचारी जाता है और उसका user account हटा दिया जाता है, तो उसने बनाई हुई keys काम करती रहती हैं। "create" क्लिक करने वाला व्यक्ति कंपनी छोड़ गया, इस कारण आपका कभी production outage नहीं होता। (उनका जाना फिर भी उन keys को rotate करने का एक अच्छा संकेत है जिन तक उनकी पहुँच थी।)
• Key की पहुँच वर्कस्पेस पर रुक जाती है। यह कभी organization-level operations नहीं कर सकती: billing, org members, org settings।

डेलिगेटेड पथ: CLI और MCP server के लिए OAuth tokens

अगले कदम

• Authentication reference: अनुरोध हेडर semantics और त्रुटि प्रतिक्रियाएँ
• Regions: regional hosts और routing
• Users, teams & roles: keys कौन प्रबंधित कर सकता है
• Workspace: वह वर्कस्पेस जिससे key बंधी होती है