如何使用Apple Business Connect API？多平台地点数据同步授权及域名疑问

一、API 域名 #

Apple Business Connect API 的基础域名是 https://businessconnect.apple.com/api/v1，所有文档中提到的端点都需要拼接在这个域名之后。比如文档里的 /locations 端点，实际请求地址就是 https://businessconnect.apple.com/api/v1/locations。

二、授权方式（OAuth 2.0 客户端凭证流） #

Apple Business Connect API 采用 OAuth 2.0 的客户端凭证流进行身份验证，具体步骤如下：

1. 创建 API 密钥
   登录你的 Apple Business Connect 账号，进入「设置」-「API 密钥」页面，点击「生成密钥」，填写密钥名称并选择对应的权限（比如地点管理选「Locations」权限）。生成后会获得一个 P8 格式的私钥文件（只能下载一次，务必妥善保存），同时记下密钥ID（kid）和你的团队ID（Team ID）（团队ID可在 Apple Developer 账号或 Business Connect 账户信息中找到）。

2. 生成 JWT 令牌
   需要用 P8 私钥签名生成 JWT 令牌，核心参数要求：

   • 头部（Header）：

     {"alg":"ES256","kid":"你的密钥ID","typ":"JWT"}
     

   • 载荷（Payload）：

     {
       "iss": "你的团队ID",
       "iat": 1690000000, // 当前 Unix 时间戳（秒）
       "exp": 1690003600, // 过期时间戳，最长不能超过当前时间+1小时
       "aud": "https://businessconnect.apple.com"
     }
     

   用 ES256 算法对头部+载荷进行签名，生成最终的 JWT 字符串。你可以用第三方库（比如 Python 的 pyjwt、Node.js 的 jsonwebtoken）来快速生成，避免手动编码出错。

3. 请求时携带授权头
   在所有 API 请求的 HTTP 头中添加：

   Authorization: Bearer 你的JWT令牌
   

   比如用 curl 测试地点列表接口：

   curl -H "Authorization: Bearer YOUR_GENERATED_JWT" https://businessconnect.apple.com/api/v1/locations
   

额外注意事项 #

• P8 私钥是敏感信息，绝对不能泄露给第三方，一旦泄露要立即在 Business Connect 后台作废该密钥。
• JWT 令牌的有效期最长为 1 小时，过期后需要重新生成。
• 如果遇到权限错误，检查生成密钥时是否勾选了对应的操作权限，以及 JWT 中的 iss、kid 是否正确。

内容的提问来源于stack exchange，提问作者Gregor