# 身份认证

Genesis 模型 API 与 Product API 使用不同的凭据和认证 Header。先确认调用目标，再只发送该接口要求的一种凭据；不要在两类 API 之间复用 Base URL、Header 或浏览器会话。

## 选择认证方式

| 调用目标 | 凭据 | 认证 Header | 额外作用域 |
| --- | --- | --- | --- |
| Genesis 模型 API | Genesis 可用的个人访问令牌或服务账号 API Key | `Authorization: Bearer <ACCESS_TOKEN>` | 模型必须对当前凭据可见。完整规则见 [Genesis 身份认证](../genesis-model-api/getting-started/authentication.md)。 |
| Product API | UC 个人访问令牌（PAT） | `X-API-Key: <PAT>` | 访问工作区资源时通常还需要 `X-Workspace-ID: <WORKSPACE_ID>`。 |

Product API 的 `X-Workspace-ID` 用于选择资源和权限作用域，不是第二个认证凭据。工作区发现接口 `GET /workspaces` 是例外，因为调用时还没有选定工作区。

## 调用 Genesis 模型 API

将当前环境提供的 Genesis Base URL 和访问凭据保存为环境变量：

```bash
export GENESIS_BASE_URL='<Complete Genesis Base URL copied from the console>'
export GENESIS_ACCESS_TOKEN='<Genesis access token>'
```

在请求中发送 Bearer 凭据：

```bash
curl "$GENESIS_BASE_URL/models" \
  -H "Authorization: Bearer $GENESIS_ACCESS_TOKEN" \
  -H "Accept: application/json"
```

请求成功后，使用响应中的模型 ID 构造后续推理请求。不同协议的 SDK 参数和版本 Header 由对应 SDK 或接口页说明，不要从一个兼容接口类推到另一个接口。

## 调用 Product API

将 Product API Base URL 和 PAT 保存为环境变量：

```bash
export PRODUCT_API_BASE_URL='<Product API Base URL ending in /newmoi>'
export PRODUCT_API_KEY='<your-personal-access-token>'
```

从当前环境的开发者接入信息取得完整 Product API Base URL，从账号凭据管理入口创建或取得 PAT。Base URL 与 PAT 是两项独立配置，不能用控制台网页地址或 Genesis 凭据替代。

先列出当前账号可见的工作区：

```bash
curl "$PRODUCT_API_BASE_URL/workspaces" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "Accept: application/json"
```

选择工作区后，将返回的工作区 ID 用于后续资源请求：

```bash
export WORKSPACE_ID='<workspace-id-from-response>'

curl -X POST "$PRODUCT_API_BASE_URL/user/info" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Accept: application/json"
```

不要同时发送 Product PAT、`Authorization` Header 和浏览器 Cookie。多种凭据同时出现会使服务无法确定调用身份，并可能直接拒绝请求。

## 安全保存凭据

- 本地验证时，通过环境变量或本机密钥工具传入凭据；退出共享终端前清理相关变量。
- 在应用和 CI/CD 中，通过部署平台或密钥管理服务注入凭据，不写入应用代码、镜像和配置样例。
- 不在 URL、查询参数、日志、截图或错误报告中记录完整凭据。
- 轮换凭据时，先更新调用方并完成只读验证，再停用旧凭据。
- 不把浏览器 Cookie 当作服务端程序的长期凭据。

## 认证和权限失败时检查

| HTTP 状态 | 先检查 | 下一步 |
| --- | --- | --- |
| `400` | Product 请求是否同时携带 `X-API-Key`、`Authorization` 或 Cookie | 只保留 Product PAT 的 `X-API-Key`，再发送请求。 |
| `401` | 凭据是否完整、有效并属于当前环境；Header 名称和 Bearer 格式是否正确 | 从当前环境重新取得或轮换凭据，先执行只读请求。 |
| `403` | Genesis 模型是否对凭据可见；Product 工作区、角色和资源权限是否正确 | 使用模型列表或工作区列表确认作用域，再检查目标资源权限。 |
| `404` | Base URL、路径和工作区是否属于当前环境 | 按[服务地址与环境](service-endpoints-environments.md)重新拼接请求。 |

认证成功只说明服务已经识别调用身份，不代表该身份拥有目标模型、工作区或资源的操作权限。收到 `403` 时不要反复轮换凭据，应先检查模型范围或 Product 资源授权。

## 下一步

- [完成 Genesis 身份认证并获取可用模型](../genesis-model-api/getting-started/authentication.md)
- [完成第一次 Product API 调用](../product-api/getting-started.md)
- [处理状态码和错误码](status-error-codes.md)