# 迁移到作用域令牌

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

旧版令牌授予对所有面向客户的 API 的广泛访问，这带来了重大的安全和运营风险。有作用域的令牌提供了更安全且更易管理的替代方案。阅读更多关于 [有作用域令牌最佳实践](https://help.impact.com/other/zh/reference-documentation/api-access-tokens-and-changelog/scoped-tokens-best-practices).

#### 迁移步骤

<details>

<summary>1. 评估您当前的集成</summary>

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

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

密切注意任何在 [API 版本](https://help.impact.com/other/zh/reference-documentation/api-access-tokens-and-changelog/api-changelog-summary)之间的破坏性更改。您应当：

* 检查您的请求负载，因为新版本可能会重命名字段、更改数据类型或要求新增字段。数据结构不匹配是运行时错误的常见来源。
* 检查响应负载的结构，因为字段可能被重命名、移除或以不同方式嵌套，这将需要更新您应用程序读取 API 响应的逻辑。

</details>

<details>

<summary>2. 生成新的有作用域令牌</summary>

在完成评估后，您可以生成新的有作用域令牌。无论您是 [品牌](https://app.gitbook.com/s/wMLlMoFBtKJa8ptd3zaw/account-administration/account-settings/api-tokens/create-an-api-access-token-as-a-brand), [合作伙伴](https://app.gitbook.com/s/b2rE79d9UhOKZQLgzSqx/account-management/account-settings/api-tokens/create-an-api-access-token-as-a-partner)，或 [代理机构](https://app.gitbook.com/s/okTNfAIjBtFchXJ9pC2q/account-settings/api-tokens/create-api-access-tokens-as-an-agency).

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

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

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

</details>

<details>

<summary>3. 测试您的集成</summary>

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

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

</details>

<details>

<summary>4. 更新您的集成</summary>

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

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

</details>

<details>

<summary>5. 通知变更</summary>

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

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

</details>
