> ## Documentation Index
> Fetch the complete documentation index at: https://docs.viggle.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 身份验证

> 验证 V1 请求身份，并使用请求 ID 追踪调用。

所有 V1 接口都需要凭据。服务端 SDK 客户端使用项目 API 密钥；Remote MCP 客户端使用 OAuth 访问令牌。

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

在 [Viggle 控制台](https://portal.viggle.ai/keys)创建和撤销密钥。请将密钥保存在服务端环境变量中，切勿暴露在浏览器代码、移动应用或公开代码仓库中。

## 示例

```bash theme={null}
curl "https://apis.viggle.ai/v1/videos/render_xxx" \
  -H "Authorization: Bearer $VIGGLE_API_KEY"
```

## 可选请求头

| 请求头               | 说明                                                    |
| ----------------- | ----------------------------------------------------- |
| `X-Request-Id`    | 客户端提供的追踪 ID。即使未主动设置，每个响应中也会包含 `X-Request-Id`，可将其记录下来。 |
| `X-Viggle-Source` | 客户端提供的标签，用于标识调用渠道或集成来源。                               |

```bash theme={null}
curl "https://apis.viggle.ai/v1/videos/render_xxx" \
  -H "Authorization: Bearer $VIGGLE_API_KEY" \
  -H "X-Request-Id: checkout-render-42" \
  -H "X-Viggle-Source: checkout-web"
```

联系支持团队时，请附上请求 ID，方便我们追踪对应请求。

## 身份验证错误

V1 错误使用统一结构：

```json theme={null}
{
  "error": {
    "code": "INVALID_CREDENTIAL",
    "message": "Invalid or expired API key",
    "retryable": false,
    "request_id": "req_123abc",
    "details": {},
    "remediation": { "action": "replace_credential", "retry_after_ms": null }
  }
}
```

`UNAUTHENTICATED` 表示完全未提供凭据；`INVALID_CREDENTIAL` 表示密钥或令牌格式错误、已撤销或已过期；`FORBIDDEN` 表示凭据有效，但无权访问所请求的资源。完整错误码与处理方式见[错误与恢复](/zh/v1/production/errors)。