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

# 身份验证

> 使用 API 密钥对发送到 Phaseo Gateway 的每个请求进行身份验证。

在[控制台](https://phaseo.app/gateway/keys)创建密钥，将其存储在服务器上，并随 Gateway 请求作为 Bearer 令牌发送。

***

## 密钥类型

* **Gateway API 密钥**用于调用工作区可用的模型、提供商和生成端点。
* **管理 API 密钥**用于调用管理 API。请参阅[管理 API 密钥](./management-api-keys.mdx)。

轮换密钥时，应先更新应用以使用替代密钥，再使旧凭据失效。参阅[密钥轮换端点](../api-reference/endpoint/keys-rotate.mdx)。

密钥格式为 `phaseo_v1_sk_<kid>_<secret>`。 请像保护密码一样保护密钥，不要将其存储在客户端代码或公开仓库中。

<Note>
  无需预存积分即可调用 `:free` 模型。付费模型需要钱包中有可用余额。
</Note>

***

## 请求头格式

每个请求都要在 `Authorization` 请求头中包含密钥：

```http theme={null}
Authorization: Bearer phaseo_v1_sk_<kid>_<secret>
```

大多数 HTTP 客户端都允许只设置一次。例如，使用 `fetch`：

```ts theme={null}
const response = await fetch("https://api.phaseo.app/v1/chat/completions", {
	method: "POST",
	headers: {
		Authorization: `Bearer ${process.env.PHASEO_API_KEY}`,
		"Content-Type": "application/json",
	},
	body: JSON.stringify({
		model: "openai/gpt-5-nano",
		messages: [
			{ role: "system", content: "You are a helpful assistant." },
			{
				role: "user",
				content: "Summarize the drawbacks to AI.",
			},
		],
	}),
});
```

***

## 密钥管理检查清单

| 做法 | 重要原因 |
| - | - |
| 每个应用使用一个密钥 | 这样轮换密钥时不会影响其他服务。 |
| 安全存储密钥 | 密钥管理器可防止密钥意外暴露在日志或错误跟踪系统中。 |
| 监控用量 | 控制台会显示各密钥的指标，便于你快速发现异常。 |
| 删除未使用的密钥 | 删除过期密钥可以缩小潜在滥用的攻击面。 |

***

## 常见身份验证错误

* **401 未授权**：密钥缺失、无效，或属于已停用的工作区。
* **403 禁止访问**：密钥存在，但无权访问请求的提供商或模型。
* **429 Too Many Requests**：密钥或工作区超出限制。参阅[速率限制](../api-reference/limits.mdx)。
* **5xx 错误**：使用指数退避后重试；如果问题仍然存在，请联系[支持团队](https://phaseo.app/help)。


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