认证 — Markdown 源文

> **AI Agents**: 索引 `/api/llms.txt` | 英文全文 `/api/llms-full-en.txt` | 中文全文 `/api/llms-full-zh.txt` | OpenAPI `/api/openapi.yaml`
> Base URL: `<BASE_URL>/v1`

# 认证

SupaNexus 使用 **Bearer API Key** 认证，与 OpenAI 客户端库兼容。

## 请求头格式

```http
Authorization: Bearer <API_KEY>
```

在 `Authorization` 请求头中携带 API Key 密钥。SupaNexus 会在每次请求时校验 Key 是否有效。

## 创建 API Key

1. 登录 [开发者控制台](https://console.supanexus.ai)。
2. 进入组织 → 项目 → **API Keys**。
3. 创建 Key 并立即复制密钥（仅显示一次）。

每个 Key 绑定 **项目** 与 **组织**，用量计入该项目。

## 过期

若 Key 设置了过期时间且已过期，返回 **401**：

```json
{
  "error": {
    "code": 401,
    "message": "Invalid credentials. Provide a valid API key in the Authorization header."
  }
}
```

## 缺失或无效 Key

| 情况 | HTTP | 响应体 |
|------|------|--------|
| 无 `Authorization` 头 | 401 | `{"error":{"code":401,"message":"..."}}` |
| Key 错误或已销毁 | 401 | 同上 |
| 服务暂时不可用 | 503 | `{"error":{"code":503,"message":"..."}}` |

## 账号封禁校验

API Key 校验通过后，SupaNexus 还会检查该 Key 所属**组织归属用户**的平台账号状态：

| 账号状态 | 控制台登录 | API `/v1/*` |
|----------|------------|-------------|
| 正常 | 允许 | 允许 |
| 已封禁 | 拒绝 | **403**，见下文 |

封禁由平台管理员执行；解封后控制台与 API 均可恢复正常使用。**封禁不会自动销毁 API Key**，但 API 会在每次请求时拦截。

```json
{
  "error": {
    "code": 403,
    "message": "Your account has been suspended. Contact support for assistance."
  }
}
```

收到该错误时请勿重试；联系平台客服或管理员处理账号状态。

## 认证不包含的内容

- **IP 限流** 对 `/v1/*` 同样返回 OpenRouter 格式 429 — 见 [限流与配额](./rate-limits-and-quotas.md)。
- **配额与余额检查** 可能在认证之后、对 `POST /v1/chat/completions` 与 `POST /v1/messages` 生效，具体取决于部署配置。

## 安全建议

- 将 Key 存放在环境变量或密钥管理系统中，勿写入代码仓库。
- 定期轮换 Key，在控制台销毁不用的 Key。
- 开发/预发/生产环境使用不同 Key。