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

# Flatkey API 身份验证：密钥、请求头与错误

> 了解如何创建 Flatkey API 密钥、通过 Authorization 请求头传递密钥，并安全处理身份验证错误。

Flatkey 使用在 `Authorization` 请求头中以 Bearer Token 传递的 API 密钥验证每个 API 请求。你可以在 Flatkey 控制台中创建和管理密钥，无需 OAuth 流程或会话管理。

## 创建 API 密钥

<Steps>
  <Step title="打开 API 密钥页面">
    登录 [console.flatkey.ai](https://console.flatkey.ai?lng=zh)，然后点击左侧边栏中的 **API 密钥**。
  </Step>

  <Step title="点击创建 API 密钥">
    为密钥设置一个便于识别的名称，例如 `production-app`、`staging` 或 `personal-testing`。名称仅供你自己识别。
  </Step>

  <Step title="立即复制密钥">
    完整密钥只会在创建时显示 **一次**。请立即复制并保存到安全位置，例如密码管理器、密钥管理服务或环境变量。如果丢失，只能重新创建。
  </Step>
</Steps>

<Warning>
  切勿将 API 密钥提交到源代码仓库，也不要把它放在浏览器端代码中。请使用环境变量，或 AWS Secrets Manager、HashiCorp Vault、Doppler 等密钥管理服务。
</Warning>

## 使用 API 密钥

在每个请求的 `Authorization` 请求头中传递密钥：

```http theme={null}
Authorization: Bearer YOUR_FLATKEY_API_KEY
```

### 使用 OpenAI SDK

OpenAI Python 和 Node.js SDK 可通过 `api_key` / `apiKey` 构造参数接收密钥：

<CodeGroup>
  ```python python theme={null}
  import os
  from openai import OpenAI

  client = OpenAI(
      api_key=os.environ["FLATKEY_API_KEY"],
      base_url="https://router.flatkey.ai/v1",
  )
  ```

  ```javascript node theme={null}
  import OpenAI from "openai";

  const client = new OpenAI({
    apiKey: process.env.FLATKEY_API_KEY,
    baseURL: "https://router.flatkey.ai/v1",
  });
  ```
</CodeGroup>

### 使用 Anthropic SDK

使用 Anthropic Python SDK 时，将 `base_url` 设置为 `https://router.flatkey.ai/v1`，并通过 `auth_token` 构造参数传入 Flatkey 密钥：

<CodeGroup>
  ```python python theme={null}
  import os
  import anthropic

  client = anthropic.Anthropic(
      auth_token=os.environ["FLATKEY_API_KEY"],
      base_url="https://router.flatkey.ai/v1",
  )
  ```

  ```javascript node theme={null}
  import Anthropic from "@anthropic-ai/sdk";

  const client = new Anthropic({
    apiKey: process.env.FLATKEY_API_KEY,
    baseURL: "https://router.flatkey.ai/v1",
  });
  ```
</CodeGroup>

### 使用 curl

```bash theme={null}
curl https://router.flatkey.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello"}]
  }'
```

## 身份验证错误

| HTTP 状态码 | 错误代码                   | 原因            | 处理方法        |
| -------- | ---------------------- | ------------- | ----------- |
| `401`    | `invalid_api_key`      | 密钥缺失、格式错误或已撤销 | 确认密钥存在且复制正确 |
| `401`    | `insufficient_balance` | 余额为 \$0.00    | 在控制台中充值余额   |
| `403`    | `model_not_allowed`    | 密钥无权访问请求的模型   | 检查密钥的模型访问设置 |

## 管理密钥

* **多个密钥**：可以按需创建任意数量的密钥，例如每个环境（dev、staging、prod）一个，或每位团队成员一个。
* **撤销密钥**：在 **API 密钥** 页面点击对应密钥旁的删除图标，撤销会立即生效。
* **密钥不会自动过期**：请按照安全最佳实践定期轮换密钥。

<Tip>
  每个部署环境使用一个独立 API 密钥。即使某个密钥泄露，也可以只撤销该密钥，不影响其他环境。
</Tip>

## 设置环境变量

推荐通过环境变量传递密钥：

```bash theme={null}
export FLATKEY_API_KEY="sk-fk-..."
```

也可以放在 `.env` 文件中（请确保 `.env` 已加入 `.gitignore`）：

```bash .env theme={null}
FLATKEY_API_KEY=sk-fk-...
```