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

# 身份验证

> 使用 API Key 对 YCloud API 请求进行身份验证。

## 基本概念

YCloud 使用 API Key 来识别您的账户并对 API 请求进行授权。请仅从受信任的服务器端代码发送密钥。

## 准备工作

在您的 YCloud 账户中创建或获取 API Key。在将密钥添加到应用程序代码之前，请确定各环境存储机密的方式。

## 请求

在每次请求的 `X-API-Key` 请求头中发送该密钥。

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://api.ycloud.com/v2/balance \
  --header "X-API-Key: $YCLOUD_API_KEY"
```

请勿添加 `Bearer` 前缀。请求头的值就是 API Key 本身。

## 响应

有效的凭据允许端点返回正常的成功响应。无效或未经授权的凭据将返回 `4xx` 错误响应。

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "error": {
    "status": 401,
    "code": "UNAUTHORIZED",
    "message": "Authentication is required.",
    "requestId": "req_1KjtKI80IKoaJNa6n6p"
  }
}
```

## 安全存储密钥

* 请将 API Key 保存在机密管理器（Secret Manager）或加密的环境变量中。
* 仅在受信任的服务器端代码中使用 API Key。
* 切勿将密钥放置在 URL、浏览器打包文件（bundle）、移动应用、日志或屏幕截图中。
* 在账户设置允许的情况下，为不同环境使用独立的密钥。
* 如果您认为密钥已泄露，请立即轮换密钥。

对于本地开发，可在 Shell 中导出密钥：

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export YCLOUD_API_KEY="YOUR_API_KEY"
```

在应用程序中从环境变量读取密钥，切勿硬编码。

## 轮换密钥

创建或选择替换密钥，将其部署到调用 YCloud 的每个服务中，验证新密钥的流量，然后撤销旧密钥。如果怀疑密钥泄露，请先轮换密钥，随后再进行排查。

## 排查身份验证问题

身份验证失败会返回 `4xx` 响应。请检查以下各项：

* 请求使用的是 `https://api.ycloud.com/v2`。
* 请求头名称完全为 `X-API-Key`。
* 密钥不包含多余的空格或引号。
* 密钥处于活动状态且属于目标 YCloud 账户。
* 该账户有权限访问端点所使用的产品。

记录响应 `requestId` 用于排查问题，但切勿记录 API Key。有关响应格式，请参阅 [错误](/zh/api-reference/guides/api-fundamentals/handle-errors)。

<Card title="测试身份验证" icon="rocket" href="/zh/api-reference/getting-started/quickstart">
  使用只读的 Balance API 请求来验证密钥。
</Card>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.