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

# 身份认证

> 通过浏览器 OAuth 或 CLOUDX_API_KEY 环境变量认证 CloudX CLI。

# 身份认证

CloudX CLI 支持两种身份认证方式：

* 使用 `cloudx auth login` 的浏览器 OAuth
* 使用 `CLOUDX_API_KEY` 环境变量的 API Key 认证

交互式本地使用时，建议使用浏览器 OAuth。CI、定时任务、脚本以及其他非交互式环境中，建议使用 API Key。

## 浏览器 OAuth

`cloudx auth login` 会启动基于浏览器的 OAuth 登录流程，并在本地保存生成的会话。

### 登录

运行：

```bash theme={null}
cloudx auth login
```

按照浏览器中的提示完成登录，然后返回终端。

### 查看状态

运行：

```bash theme={null}
cloudx auth status
```

已登录时该命令退出码为 `0`；未登录或当前登录会话不可用时退出码为 `1`。当 provisioning 服务可访问时，该命令还会显示当前组织、账户、角色以及过期时间等信息。

### 退出登录

运行：

```bash theme={null}
cloudx auth logout
```

这会退出 CLI 本地保存的当前 OAuth 会话。

## API Key

API Key 认证可以让 CLI 在没有交互式浏览器会话的环境中运行。CLI 会从 `CLOUDX_API_KEY` 读取 key，并以 bearer token 的形式发送给 CloudX。

设置了 `CLOUDX_API_KEY` 后，CLI 会优先使用它，而不是本地保存的 OAuth 会话。

只有管理员可以创建、管理和撤销 API Key。

### 创建 API Key

1. 打开 [https://app.cloudx.io/settings/api-keys](https://app.cloudx.io/settings/api-keys)。
2. 如果出现提示，请以管理员身份登录。
3. 确认您位于 **Settings > API Keys** 页面。
4. 为您的 CLI 工作流创建一个 API Key。
5. 在 key 显示时复制 key 值。

根据该 key 需要运行的命令选择权限：

| 权限                    | 允许执行                                               |
| --------------------- | -------------------------------------------------- |
| `reports:read`        | `cloudx report ...` 命令                             |
| `auctions:read`       | `cloudx auction ...` 命令                            |
| `configuration:read`  | `cloudx config show` 和 `cloudx config history`     |
| `configuration:write` | `cloudx config edit ...` 和 `cloudx config publish` |

### 使用 API Key

在 shell 中设置 key：

```bash theme={null}
export CLOUDX_API_KEY='YOUR_API_KEY'
```

然后照常运行 CLI 命令：

```bash theme={null}
cloudx auth status
cloudx report dashboard --period yesterday
cloudx auction list --period today --test-mode all
cloudx config show
```

对于 CI 或定时任务，请将 key 保存在您的密钥管理工具中，并以 `CLOUDX_API_KEY` 的形式暴露给任务。

### 验证 API Key

运行：

```bash theme={null}
cloudx auth status
```

配置了 `CLOUDX_API_KEY` 后，该命令会通过 CloudX 验证 key，并打印 API Key 详情，例如 key 名称、key ID、组织 ID、账户 ID、账户类型和权限。

如果验证失败，请检查 `CLOUDX_API_KEY` 是否设置为完整 key 值，以及该 key 是否已在 CloudX 中被删除或撤销。

### 停止使用 API Key

取消设置环境变量：

```bash theme={null}
unset CLOUDX_API_KEY
```

取消设置后，如果本地存在已保存的 OAuth 会话，CLI 会重新使用该会话。要撤销 key 本身，管理员必须从 [Settings > API Keys](https://app.cloudx.io/settings/api-keys) 删除它。

`cloudx auth logout` 只会退出本地保存的 OAuth 会话，不会撤销 API Key。

## 相关链接

* [CloudX CLI 概览](/zh/cli)
* [安装](/zh/cli/installation)
* [报表命令](/zh/cli/reporting)
* [示例](/zh/cli/examples)