迁移到范围限定令牌

旧版令牌是指在 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. 沟通变更

在确认你的新集成运行顺畅后，就该永久撤销或删除旧的、未使用的旧版令牌了。这是至关重要的安全步骤，因为一个被泄露且权限广泛的旧版令牌会带来重大风险。

最后，更新你的内部文档，并将新令牌的情况告知相关团队成员。务必记录其管理方式，以防止误用，并确保未来维护顺利进行。