服务器端 API 授权与请求格式

授权

API 请求必须通过 Authorization 请求头进行身份验证，可使用您的私密或公开 API 密钥。您可以在 App Settings 中找到这些密钥。值的格式为 Api-Key {your-secret-api-key}，例如 Api-Key secret_live_...。

Important

API 密钥与应用绑定。如果您有多个应用，请确保为每个应用使用不同的密钥。

请求格式

请求头

服务端 API 请求需要特定的请求头和 JSON 请求体。请参考以下信息构建你的请求。

Header	Description
adapty-profile-id	用户的 Adapty 用户画像 ID。可在 Adapty 看板 -> Profiles -> 具体用户画像页面的 Adapty ID 字段中查看。与 adapty-customer-user-id 可互换使用，任选其一即可。
adapty-customer-user-id	用户在您系统中的 ID。可在 Adapty 看板 -> Profiles -> 具体用户画像页面的 Customer user ID 字段中查看。与 adapty-profile-id 可互换使用，任选其一即可。 ⚠️ 仅当您在应用代码中通过 Adapty SDK 在应用中识别用户 iOS、Android、React Native、Flutter 及 Unity 识别用户时才有效。
adapty-platform	（可选）指定安装应用的设备平台。建议在 Create profile 和 Update profile 请求中修改 Installation Meta 对象时设置此参数，因为该参数取决于用户所使用的设备，而同一用户可能拥有多台设备。可选值：`iOS`、`macOS`、`iPadOS`、`visionOS`、`Android` 或 `web`。
Content-Type	设置为 `application/json`，以便 API 正确处理请求。
请求体

API 需要一个 JSON 格式的请求体，其中包含请求所需的数据。

速率限制

速率限制按 API 密钥执行，适用于您应用的限制已分配至您的密钥——没有一个适用于所有应用的统一数值。如果您正在规划高流量集成，或开始收到 429 响应，请联系支持团队确认适用于您应用的限制。

设计时需考虑以下两点：

速率限制是持续速率，而非按分钟累积的配额。 请求在时间窗口内均匀分摊，只能短暂吸收超出速率的突发流量，因此稳定的请求速率比集中在一分钟内发送等量请求效果好得多。
部分端点有各自更低的速率限制。 创建虚拟货币交易默认每个应用每分钟最多允许 600 次请求，独立于应用的整体限制之外。

超出限制的请求将返回 429 Too Many Requests。请采用退避策略重试，并在响应包含 Retry-After 头时遵照该头的指示。

轮换 API 密钥

如需轮换私密 API 密钥：

在 Settings → General 中，点击 Generate new key，然后点击旧密钥旁边的垃圾桶图标。
更新应用中使用的密钥。

下一步：请求：