# 迁移到作用域令牌
旧版令牌是指在 impact.com 于 2025 年 6 月推出作用域令牌之前创建的令牌。如果你目前仍使用旧版令牌通过 impact.com API 进行身份验证，现在是时候切换到作用域令牌了。
旧版令牌可对所有面向客户的 API 提供广泛访问，这带来了重大的安全和运维风险。作用域令牌提供了更安全、更易管理的替代方案。了解更多关于 [作用域令牌最佳实践](https://help.impact.com/other/zh/readme/api-access-tokens-and-changelog/scoped-tokens-best-practices).
#### 迁移步骤
1. 评估你当前的集成
首先，确定所有使用旧版令牌的现有集成（应用、脚本或服务）。在创建新令牌之前，你应了解切换到较新的 API 版本后可能发生哪些变化。
先列出每个集成并记录其功能、访问的具体端点、执行的操作类型（读取、写入或两者兼有），以及该集成的所有者或维护者。
请密切关注以下版本之间的任何破坏性变更 [API 版本](https://help.impact.com/other/zh/readme/api-access-tokens-and-changelog/api-changelog-summary)。你应该：
* 检查你的请求负载，因为新版本可能会重命名字段、更改数据类型，或要求新增字段。不匹配的数据结构是运行时错误的常见来源。
* 检查响应负载的结构，因为字段可能会被重命名、移除，或以不同方式嵌套，这将需要更新你应用中读取 API 响应的逻辑。
2. 生成新的作用域令牌
完成评估后，你就可以生成新的作用域令牌。请参阅我们创建作用域令牌的指南，无论你是 [品牌](https://app.gitbook.com/s/wMLlMoFBtKJa8ptd3zaw/what-would-you-like-to-learn-about/account-administration/account-settings/api-tokens/create-an-api-access-token-as-a-brand), [合作伙伴](https://app.gitbook.com/s/b2rE79d9UhOKZQLgzSqx/what-would-you-like-to-learn-about/account-management/account-settings/api-tokens/create-an-api-access-token-as-a-partner)，或 [代理商](https://app.gitbook.com/s/okTNfAIjBtFchXJ9pC2q/readme/account-settings/api-tokens/create-api-access-tokens-as-an-agency).
根据你的评估，列出你的集成所使用的每个端点，并将每个操作（例如 `GET`, `POST`, `PUT`，或 `DELETE` 映射到新 API 版本中对应的最小作用域。创建令牌时，只分配这些细粒度作用域，使其符合该集成的具体需求。
生成令牌时请选择目标 API 版本，因为这决定了它将授权的行为和数据结构。为尽量减少影响，你可以先选择与你的集成当前使用的版本一致的版本，并计划稍后单独升级。
最后，给令牌起一个能说明其用途和 API 版本的描述性名称（例如 Reporting\_v2\_Read-Only），并安全保存新凭据。
3. 测试你的集成
在正式上线之前，你应在预发布或开发环境中对更新后的集成进行彻底测试。在这个测试环境中临时更新你的集成代码，以使用新的作用域令牌和新的 API 基础 URL。执行所有主要工作流，以验证数据读取、创建、更新和删除是否按预期工作。
作为安全测试的一部分，尝试访问一个不在新令牌作用域范围内的端点。你应该收到一个 `403 Forbidden` 错误，这表明令牌正在正确限制访问。在根据你的影响评估修正任何代码后，例如更新请求/响应逻辑或字段名称，重新测试并反复迭代，直到所有功能正常工作。
4. 更新你的集成
测试成功后，你就可以将变更部署到生产环境。将所有已验证的代码更改和配置更新实施到你的生产代码库中。
这里最重要的一步是用新的作用域令牌替换旧的旧版令牌。新令牌生效后，密切监控集成和应用日志，确保没有发生意外错误。
5. 沟通变更
在确认你的新集成运行顺畅后，就该永久撤销或删除旧的、未使用的旧版令牌了。这是至关重要的安全步骤，因为一个被泄露且权限广泛的旧版令牌会带来重大风险。
最后，更新你的内部文档，并将新令牌的情况告知相关团队成员。务必记录其管理方式，以防止误用，并确保未来维护顺利进行。