Sign inGet Started

身份验证与 API 密钥

每个发往 Bird API 的程序化请求都通过一个作为 bearer token 传递的 API 密钥进行身份验证。密钥归属于某个工作区,携带可修改的权限,且完整密钥仅展示一次。
关于服务凭证与委托访问之间的区别,请参阅 API 密钥与 OAuth 令牌。

请求如何进行身份验证

在每个请求中通过 Authorization 请求头传递密钥。SDK 和 CLI 只需接收一次密钥,之后会自动设置请求头:
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.",
});
密钥前缀中的区域标识告诉你应该调用哪个主机:bk_us1_... 密钥发往 https://us1.platform.bird.com,bk_eu1_... 密钥发往 https://eu1.platform.bird.com。官方 Bird SDK 和 CLI 会从密钥中读取区域并自动选择主机。密钥发送到错误的区域主机将返回 421(类型 misdirected_error);参阅区域。
缺失或无效的密钥返回 401。有效但缺少端点所需权限的密钥返回 403。请求头语义和错误响应详见身份验证参考。

密钥结构

代码示例
bk_us1_Ab3xKq9mP2wR5tY8uI1oL4n3A3aww
└┬┘└┬┘ └──────────┬──────────┘└─┬──┘
 │  │          payload      checksum
 │  └ region (routes the request)
 └ Bird key prefix
  • 前缀:bk_{region}_ 标识凭证类型及其区域。固定且独特的前缀使密钥扫描工具能够识别代码中的 Bird 密钥,区域段则将请求路由到正确的主机。
  • 载荷:23 个随机字符,承载 136 位熵。
  • 校验和:最后 6 个字符是密钥其余部分的校验和,因此 SDK 或 API 可以在查找之前立即拒绝输入错误或被截断的密钥。
完整密钥仅在创建它的响应中返回一次。之后无法再检索明文。后续响应以 key_prefix 的形式包含前 15 个字符,例如 bk_us1_Ab3xKq9m。它们还包含一个稳定的 12 字符 fingerprint,用于在日志和支持对话中匹配密钥而不暴露其值。
如果丢失了密钥,可以轮换它以获取新密钥,或者吊销它并创建一个新密钥。

创建密钥

在仪表板的 Platform tools > API keys 下创建密钥。创建时需指定名称、一个或多个权限范围,以及可选的过期时间。创建密钥的响应是唯一携带 token 字段(完整密钥)的响应:请立即将其存储到密钥管理器中。
你也可以不通过浏览器,使用 bird api-keys create 来创建密钥。密钥签发需要 api_keys:write 权限范围,只读登录基线不包含该范围,因此请在登录时请求它:
代码示例
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
运行 bird api-keys create --example 以打印完整的请求体供编辑。
权限范围是密钥无法自行授予的唯一内容:api_keys:write 不可用于 API 密钥,因此一个密钥永远无法签发另一个密钥。签发以你的身份运行,通过仪表板会话或 CLI 或 MCP 授权。
Bird 仪表板中的 API Keys 页面,列出密钥及其掩码前缀、权限范围和最后使用时间
创建密钥后可以对其进行管理:
  • 权限范围可编辑。 编辑会替换权限集并保留原有密钥。你可以授予自己账户持有的权限范围。如果密钥在创建时尚不支持某个权限(如 voice),请轮换它以添加该权限。已吊销的密钥和已通过轮换替换的密钥无法编辑。
  • 过期时间是固定的。 当密钥需要在已知时间停止工作时(如承包商的合作期、迁移窗口),请设置 expires_at。超过该时刻后密钥返回 401;未设置过期时间的密钥在被吊销之前一直有效。
  • 密钥管理权限归于人员。 创建、编辑和吊销密钥需要 api_keys:write 权限,该权限由工作区管理员和开发者角色持有(参阅用户、团队和角色),且永远不可授予 API 密钥本身。泄露的密钥无法生成更多密钥。
API keys 页面列出每个密钥及其 key_prefix、权限范围和 last_used_on 日期(精确到天),便于你一眼发现闲置密钥。已吊销的密钥默认不在列表中显示,除非你选择展示它们。

权限范围与级别

密钥上的每个权限范围是一个 {scope, level} 对,其中 level 为 read 或 write(write 包含 read)。API 密钥持有以下权限范围:
权限范围readwrite
emails读取已发送的消息和投递状态发送电子邮件
email_management读取屏蔽列表、电子邮件配置和模板管理屏蔽列表、电子邮件配置和模板
email_marketing读取联系人、受众和广播管理联系人、受众和广播
domains读取发送域及其 DNS 记录添加、验证和管理发送域
sms读取已发送的 SMS 和投递状态发送 SMS
sms_management读取发送者、注册信息、屏蔽列表、关键字回复、目标和模板管理发送者、注册信息、屏蔽列表、关键字回复、目标和模板
whatsapp读取已发送的 WhatsApp 消息和状态发送 WhatsApp 消息
whatsapp_management读取 WhatsApp 模板和设置管理 WhatsApp 模板和设置
verify读取验证状态发送和检查验证码
realtime读取 Realtime 应用、频道和频道成员创建应用和发布事件
voice读取通话段日志和通话统计验证 SIP 通话并创建会话凭证
voice_management读取中继、网关、号码、来电显示 ID 和目标管理中继、网关、号码、来电显示 ID 和目标
mailbox读取邮箱、会话和消息发送和回复邮箱消息
mailbox_management读取接收规则和邮箱配置创建、更新和删除邮箱及接收规则
assets读取资源和文件夹上传、更新和删除资源及文件夹
workspace读取工作区名称、组织 ID 和设置不可用
webhooks读取 webhook 订阅及其投递尝试创建、更新、删除、测试、重放和轮换 webhook 密钥
lookup不可用查询电话号码、电子邮件地址和身份匹配
更改工作区设置、管理成员、签发密钥和管理 IP 池被有意设计为不可授予 API 密钥,因此它们以人员身份而非密钥身份运行:通过仪表板,或通过持有该权限范围的 CLI 或 MCP 服务器上的授权。授予最小够用的权限集:一个仅用于发送电子邮件的密钥应只持有 emails:write,不包含其他权限。
lookup 没有读取级别的操作:每个查询端点(包括获取已有结果)都需要 write。

吊销密钥

在 Platform tools > API keys 下从密钥所在行吊销密钥。吊销是永久性的:被吊销的密钥无法重新激活,其记录会保留用于审计,且 revoked_at 已设置。
吊销传播速度快但并非即时生效。密钥验证经过短时缓存,因此刚吊销的密钥可能在几秒内(最多五秒)继续工作,之后所有使用该密钥的请求都会返回 401。

轮换密钥

轮换会为你已有的密钥签发一个替代密钥,并在该响应中返回其 token(仅此一次)。替代密钥继承源密钥的名称、权限范围和源 IP 限制,且初始没有过期时间。在 Platform tools > API keys 下从密钥所在行轮换,或通过 bird api-keys rotate 和 api_keys_rotate MCP 工具在无浏览器环境下操作:
代码示例
bird auth login --scope api_keys:write
bird api-keys rotate key_01hqz8kp3v9x2m --yes
旧密钥在宽限期内继续有效(默认 24 小时),以便你在旧密钥失效前部署新令牌。传入 grace_period: 0(在 CLI 上为 --grace-period 0)可立即吊销旧密钥,这适用于密钥泄露的情况:没有重叠期,所有仍携带旧密钥的请求会立即失败。如果密钥已设置的过期时间早于宽限期结束,则保留其自身的过期时间,因为轮换永远不会延长密钥的有效期。
在自动化密钥轮换之前,请注意两个限制。轮换不会继承过期时间,因此替换一个在已知时间过期的密钥后,新密钥将一直有效直到被撤销;如果过期时间很重要,请使用 create 重新签发。此外,一个密钥只能轮换一次:对同一密钥的第二次轮换会返回 409,因此请发送 Idempotency-Key,这样重试时会重放原始响应。如果没有发送,一次你未收到回复的轮换已经生成了一个活跃密钥,而你无法再读取它的令牌。
当你无法预测切换需要多长时间时,手动重叠两个密钥仍然是更安全的方式,因为宽限期在轮换时已固定,之后无法延长:
  1. 创建一个具有相同权限范围的新密钥。
  2. 将新密钥部署到你的服务中。
  3. 观察旧密钥的 last_used_on,直到流量已切换完毕。
  4. 吊销旧密钥。

密钥归属于工作区

API 密钥绑定到你的工作区,并以该工作区的权限进行身份验证。创建者的个人权限不影响密钥。这带来两个实际结果:
  • 密钥不受人员离职影响。 当员工离职且其用户账户被移除时,他们创建的密钥仍然有效。你不会因为点击 "create" 的那个人离开公司而导致生产中断。(他们的离职仍然是轮换其有权访问的密钥的好时机。)
  • 密钥的作用范围止于工作区。 它永远无法执行组织级操作:账单、组织成员、组织设置。
由于密钥锁定工作区,使用密钥的请求无需额外上下文;参阅工作区了解工作区及其上级组织如何划分可访问的内容。

委托路径:用于 CLI 和 MCP 服务器的 OAuth 令牌

API 密钥用于服务。Bird CLI 和 Bird MCP 服务器 在用户登录时使用 OAuth。你通过浏览器登录,选择一个工作区,并授予你权限的一个子集。工具随后会收到一个短期有效的 bt_{region}_... 用户令牌。
每个令牌仅限于你持有的权限。你可以在 Profile > Connected apps 下撤销每个工具的访问权限。这些工具会为你管理令牌,因此不要复制或存储到密钥管理器中。服务器工作负载请使用 API 密钥。

后续步骤