> For the complete documentation index, see [llms.txt](https://help.impact.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.impact.com/other/zh/reference-documentation/api-access-tokens-and-changelog/migrate-to-scoped-tokens.md).
# 迁移到作用域令牌
旧版令牌是指在 impact.com 于 2025 年 6 月推出作用域令牌之前创建的令牌。如果你目前仍使用旧版令牌通过 impact.com API 进行身份验证，现在是时候切换到作用域令牌了。
旧版令牌可对所有面向客户的 API 提供广泛访问，这带来了重大的安全和运维风险。作用域令牌提供了更安全、更易管理的替代方案。了解更多关于 [作用域令牌最佳实践](/other/zh/reference-documentation/api-access-tokens-and-changelog/scoped-tokens-best-practices.md).
#### 迁移步骤
1. 评估你当前的集成
首先，确定所有使用旧版令牌的现有集成（应用、脚本或服务）。在创建新令牌之前，你应了解切换到较新的 API 版本后可能发生哪些变化。
先列出每个集成并记录其功能、访问的具体端点、执行的操作类型（读取、写入或两者兼有），以及该集成的所有者或维护者。
请密切关注以下版本之间的任何破坏性变更 [API 版本](/other/zh/reference-documentation/api-access-tokens-and-changelog/api-changelog-summary.md)。你应该：
* 检查你的请求负载，因为新版本可能会重命名字段、更改数据类型，或要求新增字段。不匹配的数据结构是运行时错误的常见来源。
* 检查响应负载的结构，因为字段可能会被重命名、移除，或以不同方式嵌套，这将需要更新你应用中读取 API 响应的逻辑。
2. 生成新的作用域令牌
完成评估后，你就可以生成新的作用域令牌。请参阅我们创建作用域令牌的指南，无论你是 [品牌](/brand/zh/what-would-you-like-to-learn-about/account-administration/account-settings/api-tokens/create-an-api-access-token-as-a-brand.md), [合作伙伴](/partner/zh/ni-xiang-liao-jie-shen-me/account-management/account-settings/api-tokens/create-an-api-access-token-as-a-partner.md)，或 [代理商](/agency/zh/what-would-you-like-to-learn-about/account-settings/api-tokens/create-api-access-tokens-as-an-agency.md).
根据你的评估，列出你的集成所使用的每个端点，并将每个操作（例如 `GET`, `POST`, `PUT`，或 `DELETE` 映射到新 API 版本中对应的最小作用域。创建令牌时，只分配这些细粒度作用域，使其符合该集成的具体需求。
生成令牌时请选择目标 API 版本，因为这决定了它将授权的行为和数据结构。为尽量减少影响，你可以先选择与你的集成当前使用的版本一致的版本，并计划稍后单独升级。
最后，给令牌起一个能说明其用途和 API 版本的描述性名称（例如 Reporting\_v2\_Read-Only），并安全保存新凭据。
3. 测试你的集成
在正式上线之前，你应在预发布或开发环境中对更新后的集成进行彻底测试。在这个测试环境中临时更新你的集成代码，以使用新的作用域令牌和新的 API 基础 URL。执行所有主要工作流，以验证数据读取、创建、更新和删除是否按预期工作。
作为安全测试的一部分，尝试访问一个不在新令牌作用域范围内的端点。你应该收到一个 `403 Forbidden` 错误，这表明令牌正在正确限制访问。在根据你的影响评估修正任何代码后，例如更新请求/响应逻辑或字段名称，重新测试并反复迭代，直到所有功能正常工作。
4. 更新你的集成
测试成功后，你就可以将变更部署到生产环境。将所有已验证的代码更改和配置更新实施到你的生产代码库中。
这里最重要的一步是用新的作用域令牌替换旧的旧版令牌。新令牌生效后，密切监控集成和应用日志，确保没有发生意外错误。
5. 沟通变更
在确认你的新集成运行顺畅后，就该永久撤销或删除旧的、未使用的旧版令牌了。这是至关重要的安全步骤，因为一个被泄露且权限广泛的旧版令牌会带来重大风险。
最后，更新你的内部文档，并将新令牌的情况告知相关团队成员。务必记录其管理方式，以防止误用，并确保未来维护顺利进行。
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://help.impact.com/other/zh/reference-documentation/api-access-tokens-and-changelog/migrate-to-scoped-tokens.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.