迁移到作用域令牌

旧版令牌指的是在 impact.com 于 2025 年 6 月推出有作用域令牌之前创建的令牌。如果您当前使用旧版令牌对 impact.com API 进行身份验证，现在是切换到有作用域令牌的时候了。

旧版令牌授予对所有面向客户的 API 的广泛访问，这带来了重大的安全和运营风险。有作用域的令牌提供了更安全且更易管理的替代方案。阅读更多关于 有作用域令牌最佳实践.

迁移步骤

1. 评估您当前的集成

首先，识别所有使用旧版令牌的现有集成（应用、脚本或服务）。在创建新令牌之前，您应了解切换到较新 API 版本时可能发生的变化。

从列出每个集成开始，并记录其功能、访问的具体端点、执行的操作类型（读取、写入或两者）以及谁拥有或维护该集成。

密切注意任何在 API 版本之间的破坏性更改。您应当：

• 检查您的请求负载，因为新版本可能会重命名字段、更改数据类型或要求新增字段。数据结构不匹配是运行时错误的常见来源。

• 检查响应负载的结构，因为字段可能被重命名、移除或以不同方式嵌套，这将需要更新您应用程序读取 API 响应的逻辑。

2. 生成新的有作用域令牌

在完成评估后，您可以生成新的有作用域令牌。无论您是 品牌, 合作伙伴，或 代理机构.

根据评估，列出您集成使用的每个端点，并将每个操作（例如 GET, POST, PUT，或 DELETE ）映射到新 API 版本中的相应最小作用域。创建令牌时，您只会分配这些细粒度的作用域，使其针对集成的具体需求进行定制。

在生成令牌时选择目标 API 版本，因为这决定了其授权的行为和数据结构。为尽量减少中断，您可以先匹配集成当前使用的版本，并计划稍后单独升级。

最后，为令牌命名一个能表明其用途和 API 版本的描述性名称（例如 Reporting_v2_Read-Only），并安全保存新凭证。

3. 测试您的集成

上线之前，您应在暂存或开发环境中彻底测试更新后的集成。在此测试环境中暂时更新集成代码以使用新的有作用域令牌和新的 API 基础 URL。执行所有主要工作流以验证数据读取、创建、更新和删除是否按预期工作。

作为安全测试的一部分，尝试访问不在新令牌作用域覆盖范围内的端点。您应收到 403 Forbidden 错误，这确认令牌正在正确限制访问。在根据您的影响评估更正任何代码（例如更新请求/响应逻辑或字段名称）后，重新测试并迭代，直到所有功能正常工作。

4. 更新您的集成

成功测试后，您就可以将更改部署到生产环境。在生产代码库中实施所有经过验证的代码更改和配置更新。

此处最重要的一步是将旧的旧版令牌替换为新的有作用域令牌。一旦新令牌生效，请密切监控集成和应用日志，以确保没有出现意外错误。

5. 通知变更

在确认新集成运行正常后，是时候永久撤销或删除旧的、未使用的旧版令牌了。这是一个关键的安全步骤，因为具有广泛权限的被泄露旧版令牌会带来重大风险。

为完成该流程，请更新内部文档并通知相关团队成员有关新令牌的信息。务必记录其管理方式以防止滥用并确保未来的顺利维护。