身份验证
每个 API 请求都通过在 Authorization 请求头中以 bearer token 形式传递 API 密钥来进行身份验证：
代码示例
curl https://us1.platform.bird.com/v1/email/messages \
-H "Authorization: Bearer bk_us1_Ab3xKq9mP2wR5tY8uI1oL4nJ..."密钥的作用域为工作区级别：一个密钥代表你的工作区进行身份验证，携带创建时选择的权限范围，并且只能访问该工作区的资源。如何创建、设定范围、轮换和吊销密钥，请参阅身份验证与 API 密钥指南：在控制台的 Developers > API keys 下创建密钥，或通过 bird api-keys create 以无浏览器方式创建。本页介绍线路级协议。
密钥格式
代码示例
bk_us1_Ab3xKq9mP2wR5tY8uI1oL4nJ...
└┬┘└┬┘ └──────────┬──────────┘└┬┘
│ │ payload checksum
│ └ region (routes the request)
└ Bird key prefix密钥由 bk_{region}_{payload}{checksum} 组成：
- bk_{region}_：前缀标识凭据类型和密钥创建所在的区域。bk_us1_ 密钥仅对 https://us1.platform.bird.com 有效，bk_eu1_ 密钥仅对 https://eu1.platform.bird.com 有效。官方 SDK 和 CLI 使用此前缀来选择主机。固定的 bk_ 前缀已注册到 GitHub secret scanning，因此在公开仓库中泄露的 Bird 密钥会被检测并报告。
- 载荷：一个具有 128 位以上熵的长随机字符串。
- 校验和：最后 6 个字符是密钥其余部分的校验和，客户端可在发送请求之前在本地拒绝输入错误或被截断的密钥。
完整密钥仅在创建密钥的响应中返回一次。明文无法再次获取，控制台仅显示一个简短的 key_prefix（前 12 个字符）。如果密钥丢失，请吊销并替换。
失败响应
所有失败均使用标准错误响应。
| 状态码 | 触发条件 |
|---|---|
| 401 | Authorization 请求头缺失、密钥格式错误或未知，或密钥已被吊销。 |
| 403 | 密钥有效，但缺少端点所需的权限范围。 |
| 421 | 密钥的区域与主机不匹配，例如将 bk_eu1_... 密钥发送到 us1.platform.bird.com。 |
421 Misdirected Request 响应体（错误类型 misdirected_error，错误码 E01010）会指明正确的区域主机，客户端无需猜测即可检测错误并重新发送。请参阅基础 URL 与区域。
控制台会话不是 API 密钥
Bird 控制台不使用 API 密钥：用户登录后获得一个会话 cookie，其权限范围为该用户自身的权限。会话 cookie 不被编程 API 接口接受，API 密钥也不被控制台接受。服务端工作负载始终使用 API 密钥。
相关内容
- 身份验证与 API 密钥指南：创建、设定范围、轮换和吊销密钥
- 基础 URL 与区域：区域主机和区域模型
- 错误：错误响应与错误目录