接入入口与权限
后台自动运行的任务选择应用身份权限；代表当前登录用户操作时选择用户身份权限。同一应用可以启用两种身份，分别配置凭证和权限。
本文介绍两种调用身份的适用场景、接入地址和授权条件。登录成功后，API 仍会校验当前应用、调用身份、API 权限、企业范围和资源权限。
开发者后台显示 应用身份权限 和 用户身份权限；接口和诊断信息中的 identity_type、OAuth Profile 对应这两种身份的配置。
选择调用身份
| 场景 | 调用身份 | 是否需要 Client Secret | 调用主体 |
|---|---|---|---|
| 定时任务、后台同步、服务间调用 | 应用身份权限 | 需要，只保存在服务端 | 当前 Application |
| 用户登录后查看或操作自己的数据 | 用户身份权限 | 不需要，使用 PKCE | 当前 Application + 当前用户 |
| 产品同时有前台用户操作和后台任务 | 两种都启用并分别申请 API 权限 | 两套配置分开 | 每个请求只选择其中一种 |
应用身份不能借用用户权限，用户 Token 也不能用于无人值守任务。Sandbox 与 Production 中的两种身份都分别配置和启用，不会跨环境复制。
已开通应用身份权限时，仍可切换到“用户身份权限”为同一 API 产品单独申请；反向操作同样适用。调整已有授权会保留当前勾选的权限，确认后更新该身份的授权，不影响另一种身份。
基本概念
| 名称 | 说明 |
|---|---|
| 应用（Application） | 产品在某个环境中的接入配置 |
| API 权限 | 允许调用哪些操作、访问多大数据范围；协议配置中会映射为 Scope |
| 访问令牌（Token） | 调用 API 时携带的短期身份证明，不是长期密码 |
| 目标 API（Audience） | 访问令牌允许使用的目标 API |
| OAuth Client | 平台为一种调用身份签发的认证配置；由平台创建，开发者不手工管理 |
配置和接口使用括号内的协议标识，可用于核对参数和排查错误。
部署环境（development|test-us|production）决定接入地址和服务可用性；Application 环境（sandbox|production）决定应用资源用于测试还是生产。
在当前页面完成配置
应用本身显示待配置时，先在当前页面点击“完成配置并启用”，无需补填信息。读取到应用已启用后，再配置调用身份；不要重复创建应用。
后台任务选择“应用身份权限”，点击“启用应用身份”，无需填写登录回调，也不必另建应用。已有应用身份显示待配置时，仍在这里启用，平台沿用已有身份；API 权限按需另选，不会复制用户权限。
启用配置已保存但页面尚未更新时，点击“重新读取当前应用”。该操作只读取状态，无需再次创建或启用。结果尚未确认时，点击“恢复原启用请求”；原请求确认前不另开一个创建操作。
进入应用的“API 与权限”，选择调用身份。尚未启用用户身份时，直接填写一个精确 HTTPS 登录回调，点击“配置并启用”；退出地址和网站来源会自动补全，需要自定义时再展开高级设置。也可在 OAuth/OIDC 页完成同样的配置，无需重复填写。仅接入用户登录时，不必申请业务 API 权限。
页面提示配置已保存但尚未读取到用户身份时，点击“重新读取用户身份”，无需再次配置。结果尚未确认时，按页面提示恢复原请求；确认当前状态后再继续。
已有用户身份显示待配置时，页面会展示已保存的地址，点击“完成配置并启用”，无需重填回调。启用身份或待配置的 API 授权后，已保存但状态尚未更新时点击“重新读取当前状态”，不会重复写入。
开通 API 权限时，先选择产品，再点击“开通权限”，弹窗会沿用当前产品。可按名称或 Scope 搜索，查看关联 API、事件和数据范围，再勾选实际需要的权限。Token 模型等专用接口的说明默认收在“Token API 接入说明（可选）”，仅按产品需要展开。
开通或调整权限的结果尚未确认时，所选权限会保留并锁定，点击“重试原请求”恢复，不必重新勾选。页面要求重新验证身份时，完成验证后再手动重试，不会自动提交。权限或配置已变化时，取消弹窗会重新读取当前应用，核对后再操作；未确认的响应不会显示为保存成功。
以上为操作示意；实际可用身份、产品和权限以当前页面为准。创建者自动成为应用所有者，无需额外创建平台角色；协作者使用当前应用已授予的权限。
查看和管理 API 权限
权限列表保留当前调用身份和产品分类。可以按权限名称、Scope 或 API 路径搜索，并按权限状态、敏感级别筛选。
| 位置 | 操作与结果 |
|---|---|
| 权限名称 | 查看权限名称、Scope 和用途说明 |
| 权限类型 | 区分应用身份和用户身份 |
| 权限状态 | 查看是否已启用；展开“授权同步”核对配置是否一致 |
| 可访问的数据范围 | 查看当前身份的资源边界；用户权限、客户授权和资源访问限制仍分别校验 |
| 相关 API／事件 | 在行内浮层查看关联 API 方法、路径和事件，无需离开列表 |
| 接入示例与配置 | 按需展开复制配置和调用示例 |
数据范围显示“暂不可核验”时，不代表可以访问全部资源。API 权限也不会自动产生客户资源授权；涉及客户资源时，可在“客户授权”工作台查看已有授权。
关闭权限
- 在权限所在行点击“关闭”；同时关闭多项时，选择“批量处理 → 批量关闭权限”。
- 单项关闭直接核对当前权限；批量关闭时勾选权限，也可以搜索后选择当前结果。未选择的权限会保留。
- 检查选中数量和保留数量，点击“确认关闭”。
关闭立即更新对应 API 授权，调用可能因此失败。事件订阅单独配置，不会因关闭 API 权限而自动删除。关闭某产品最后一项权限后，仍可在原产品重新开通，无需创建新应用或更换调用身份。
请求失败或结果未确认时，选择会锁定。可以“重试原请求”，或取消并重新读取当前应用；不要另建一个关闭请求来猜测结果。
批量导入和导出
在“批量处理 → 批量导入／导出权限”中：
- 在“导出”页复制当前应用的权限 JSON。文件包含产品代码、版本、调用身份和 Scope，不包含凭据或客户资源授权。
- 在目标应用的“导入”页粘贴 JSON，点击“检查新增权限”。
- 核对预览后，点击“确认新增权限”。导入只新增权限，不会移除已有权限。
无需填写应用 ID、回调地址或申请理由。两种身份都可在同一次导入中配置，但对应身份必须已经启用，且当前产品版本允许这些权限。任一条目不可申请时，检查阶段会阻止整批提交。
提交后按产品显示完成进度。部分完成后遇到错误，已完成项会保留，重试从失败的原请求继续；关闭弹窗后可重新读取应用核对结果。导入并非所有产品共同提交的单个事务。
统一入口
接入地址按部署环境分别提供。sandbox 应用可在 Development 或 test-us 联调。请从当前环境配置获取公开 Origin，从已开通的 API 产品获取 Base URL 和受支持路径，不能根据域名后缀推算地址。
Sandbox Application 的测试入口
| 用途 | 入口 | 使用者 | 说明 |
|---|---|---|---|
| 开发者文档 | ${GOODVISION_DEVELOPER_DOCS_ORIGIN} | 所有接入团队 | 匿名阅读，不建立登录 Session |
| Developer Console | 当前文档站点的 /console/ | 使用本人账号的开发者 | Application、应用身份/用户身份 API 权限、事件和 Sandbox 进度 |
| Identity / OIDC Issuer | ${GOODVISION_IDENTITY_ISSUER} | 用户和服务 | OAuth 2.0 / OIDC；只负责认证和 Token |
| Open API | ${GOODVISION_API_BASE} | 已批准的 Application | 只调用已签发 API Product 中列出的路由 |
| Webhook Origin | ${GOODVISION_WEBHOOK_ORIGIN} | 已批准的 Application | 使用当前 Webhook 配置提供的地址范围 |
Development 和 test-us 分别提供文档、身份认证、API 和 Webhook 地址，仅用于隔离的 Sandbox 测试资源。使用当前环境提供的一组地址，不能拼接另一环境的配置。
正式环境（Production）
| 用途 | 入口 | 使用者 | 说明 |
|---|---|---|---|
| 开发者文档 | ${GOODVISION_DEVELOPER_DOCS_ORIGIN} | 所有接入团队 | 只提供静态文档，不承载登录 Session 或 API |
| Developer Console | 按生产接入合同开通 | 已获生产批准的外部开发者 | 本文档不发布通用正式入口；以生产接入合同为准 |
| Identity / OIDC Issuer | ${GOODVISION_IDENTITY_ISSUER} | 已获生产批准的用户和服务 | 必须精确校验 Discovery 返回的 issuer |
| Open API | ${GOODVISION_API_BASE} | 已获生产批准的 Application | 只调用生产 API Product 契约中列出的路由 |
| Webhook Origin | ${GOODVISION_WEBHOOK_ORIGIN} | 已获生产批准的 Application | 使用正式环境 Webhook 配置提供的地址范围 |
文档和控制台可能使用同一域名，控制台位于 /console/。API、OIDC Issuer 和 Webhook 使用各自的配置地址，不能从文档域名推导。
进入 Production 前，重新创建或配置 Application、两种身份的 OAuth Client、Issuer、Audience、凭证、API 调用授权、用户同意／委托、数据、Webhook 和配额。Sandbox 配置不能跨环境复用。
当前业务 Production 发布目标尚未确定，正式接入以开通说明为准。
配置入口
在开发者后台创建应用、申请 API 产品和 Webhook，再按已开通的接口说明调用。平台负责验证配置、提供凭证和检查企业范围；每个业务 API 还会检查具体资源权限。第三方通过这些公开入口完成接入。
API 授权条件
所有请求先检查四项共同条件：访问令牌有效且来自当前 Application 的正确身份、目标 API 和 API 权限匹配、当前身份的 API 调用授权已生效、目标组织和具体资源允许访问。
请求依次通过以下检查：
- 统一身份服务校验 Token 的签名、有效期和目标 API。
- 统一权限服务检查调用方是否有权进入所选 Organization，以及产品、角色、权益和委托是否仍有效。
- 开放平台检查当前 Application/身份是否申请并获批了这个 API Product、Scope、环境和配额。
- 业务 API 最后检查具体 Tenant、Account 和资源 ACL。
Partner 代表 Customer 操作时，调用可以同时选择 Customer 的 organization_id 和 Partner 的 acting_organization_id。这两个值只是“选择哪套上下文”，不是权限本身；平台会重新核验已批准的委托关系。调用方不能通过修改 Header、URL 或前端状态来增加角色、Scope 或资源范围。
在 Developer Console 中，这类上下文会显示为“受托访问”。organization_id 表示正在访问数据的 Customer，acting_organization_id 表示代表 Customer 操作的 Partner。页面只能选择平台已经返回的组合；BFF 会在服务端保存并同时转发两个值，平台再次核验。切换 Partner 不会自动获得新的权限。
然后根据调用方式增加不同检查：
| 应用身份权限 | 用户身份权限 |
|---|---|
| 访问令牌来自应用身份客户端 | 访问令牌来自用户身份客户端 |
| 使用应用身份的 API 调用授权 | 使用用户身份的 API 调用授权 |
| 应用身份在目标组织有权 | 用户已同意所需 Scope |
| 不读取或继承用户 Role | 平台用户委托仍有效 |
| 业务 API 检查应用可访问的数据范围 | 统一权限服务和业务 API 检查当前用户权限 |
Token、应用 API 调用授权、用户同意或委托、企业范围和资源权限需要同时有效。任一检查失败，请求都会被拒绝。
菜单可见、控制台显示“已启用”或 JWT 中出现某个 Claim，都不能单独证明最终有权。请求中的 organization_id、account_id 或 user_id 也不能扩大服务端计算出的范围。
配置与启用步骤
- 使用本人账号登录；首次没有企业时自动准备个人空间。协作已有企业的应用时，加入该企业并取得当前应用权限。
- 创建 Sandbox 应用，填写名称；代码自动生成，创建者自动成为应用所有者。
- 按场景启用应用身份、用户身份或两者，平台自动准备对应的独立 OAuth Client。用户身份需要精确 Callback URL；应用身份的 Secret 只保存在服务端。
- 需要业务 API 时，再在当前身份下选择 API Product 和最小 API 权限；仅登录不要求业务 API 授权。一个申请不能同时包含两种身份。
- 平台自动校验调用身份、Scope 允许的身份类型、数据范围和配额；用户 Consent 保持独立校验。
- 自动校验通过后，平台将所选 API 权限和目标 API 绑定到当前身份的 OAuth Client，并直接启用本次 API 调用授权。
- 查看配置校验结果：一致时显示“已绑定”，缺失或不匹配时显示“配置漂移”，暂时无法检查时显示“暂不可核验”。
- 应用身份的 Secret 按页面显示的方式获取或轮换；用户身份明确显示“无需 Client Secret”。
- 按“Sandbox 与上线”中的动态清单验证当前实际启用的能力，再申请 Production。已用 API 验证 Audience、组织、最小权限、跨身份／跨组织拒绝和撤权；已用事件验证相应接收方式及故障恢复。未使用的 API、事件或服务凭据不是登录或上线前置。
当前身份的服务凭据操作使用 POST /api/developer/v1/applications/{applicationId}/oauth-profiles/{profileId}:reveal-credential 和 :rotate-credential。只有 service Profile 可以调用这两个操作；user Profile 永远没有 Secret。响应始终为 no-store，轮换必须带 Idempotency-Key，旧 Secret 会立即失效。
撤销一种身份后，该身份的新请求会被拒绝，另一种身份的配置保留。
401 与 403 排查
| 结果 | 常见原因 | 处理方式 |
|---|---|---|
401 | Token 缺失、过期、签名无效、Issuer/Audience 错误 | 重新获取当前环境 Token；按 Discovery 和 API Product 契约核对 iss、aud |
401 session_expired 后台登录失效 | 当前登录已过期或无法继续使用 | 从原页面重新登录即可，无需手动清理 Cookie；同账号且当前范围有效时保留普通草稿，不自动重放业务操作 |
403 企业或应用无权 | 当前成员或应用权限不足、已撤销 | 联系该企业或应用负责人；明确选择有权范围，不静默切换或换用他人账号 |
403 identity_mismatch | Token 来自另一种身份的 Client，或使用了另一身份的 API 调用授权 | 在“API 与权限”确认当前选择的是应用身份还是用户身份，并重新获取对应 Token |
403 scope_denied | 当前身份的 API 调用授权未批准、已撤销，或 Scope 不包含该操作 | 在 Developer Console 核对 Application、调用身份、API Product、环境和权限状态 |
403 organization_denied | Token/Application 与请求 Organization 或 ProductTenant 不匹配 | 使用已批准的组织上下文；不能通过请求头覆盖服务端上下文 |
403 resource_denied | 资源 ACL、状态或审批不允许当前操作 | 保存请求 ID，联系 API 产品支持人员核对资源范围和状态 |
503 | 当前无法完成权限或资源检查 | 保存请求 ID，按退避策略重试；确认前继续限制访问 |
已登录后遇到“工作区暂不可用”，点击重新读取工作区即可继续，无需重复登录或申请权限。页面会重新核验登录和当前企业；若登录已过期或企业访问已撤销，再按相应提示处理。
排障时只提交 Application ID、环境、API Product、请求 ID、错误码和时间，不提交 Token、Client Secret、Cookie 或 Webhook Secret。
接入方边界
- 只通过 Developer Console 申请接入资源，通过已签发 API Product 调用业务 API。
- 不调用平台管理接口，也不使用内部账号或共享管理员 Token 运行第三方系统。
- 不从源码、示例路径、DNS 或内部服务地址推测可用 API。
- 一个产品和用途使用一个逻辑 Application；前台用户调用与后台任务在其中使用独立身份和凭证。Sandbox 与 Production 仍使用不同 Application 并完全隔离。
当前用户授权接口的完整参数与恢复规则见用户授权。
登录后的客户空间
仅用户登录时，平台通过用户与客户空间准备默认个人空间。开发者企业管理应用，不能当作所有客户的请求范围。该接口启用状态与业务 API 权限分开。