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

# 鉴权

> 使用 API Key 鉴权 EggAPI 请求

EggAPI 产品里有两类鉴权：

* 公开的服务端 API 调用使用 API Key。
* 网站 dashboard 和 admin 工具使用 Better Auth session cookie。

本文只说明公开 API Key 调用方式。

## API Key 请求头

每个公开 API 请求都要把 API Key 放在 Bearer Token 请求头里：

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

示例：

```bash theme={null}
curl https://api.eggapi.ai/v1/usage/summary \
  -H "Authorization: Bearer YOUR_API_KEY"
```

如果请求头缺失、格式不是 `Bearer <token>`、Key 被停用或过期、所属用户不是 active，后端都会拒绝请求。

## 创建 API Key

请在 EggAPI dashboard 里创建和管理 API Key。创建 Key 是 dashboard session 行为，不应该从后端批处理任务或面向用户的前端直接调用。

Key 创建后请立即保存。API Key 应像密码一样处理，只放在服务端环境里使用。

## 哪些端点接受 API Key

<CardGroup cols={2}>
  <Card title="生成" icon="wand-magic-sparkles" href="/docs/zh/api-reference/introduction">
    `POST /v1/generate` 接受 API Key，也支持 dashboard playground 的 session 鉴权。
  </Card>

  <Card title="任务" icon="clock" href="/docs/zh/guides/async-tasks">
    `GET /v1/tasks/{id}` 和 `GET /v1/tasks` 接受 API Key，也支持 session 鉴权。
  </Card>

  <Card title="用量" icon="chart-line" href="/docs/zh/api-reference/introduction">
    `GET /v1/usage` 和 `GET /v1/usage/summary` 必须使用 API Key。
  </Card>

  <Card title="Dashboard" icon="user" href="https://eggapi.ai/dashboard">
    API Key 管理、余额和 webhook secret 管理使用浏览器 session。
  </Card>
</CardGroup>

## 安全建议

* API Key 只放在服务端，不要暴露在前端 JavaScript、移动端、公开仓库或日志中。
* 为生产、预发和本地开发分别创建不同的 Key。
* 如果怀疑 Key 泄露，立即轮换。
* 浏览器用户需要触发 EggAPI 生成时，优先经过你自己的后端接口转发。

## 常见鉴权错误

```json theme={null}
{
  "data": null,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing Authorization header"
  }
}
```

```json theme={null}
{
  "data": null,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid Authorization format, expected 'Bearer <token>'"
  }
}
```

```json theme={null}
{
  "data": null,
  "error": {
    "code": "FORBIDDEN",
    "message": "User account is suspended"
  }
}
```


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