---
title: API Key 认证 (API Key Authentication)
created: 2025-04-15
updated: 2026-05-01
type: concept
tags: []
sources: []
---

# API Key 认证 (API Key Authentication)

**通过预共享密钥验证客户端身份的简单认证机制**，常见于 API 网关和微服务间通信。

## 常见形式

| 形式 | HTTP 头格式 | 示例 |
|------|------------|------|
| API Key | `X-API-Key: <key>` | `X-API-Key: sk-abc123` |
| Bearer Token | `Authorization: Bearer <token>` | `Authorization: Bearer eyJ...` |
| Basic Auth | `Authorization: Basic <base64>` | `Authorization: Basic dXNlcjpwYXNz` |

## 在反向代理层实现

API Key 认证最适合在 [[reverse-proxy-authentication|反向代理层]] 实现——网关检查请求头，未携带有效 Key 的请求在到达后端前即被拒绝。

### 单 Key 校验
```
@unauthorized { not header X-API-Key "the-key" }
respond @unauthorized "Unauthorized" 401
```

### 多 Key 白名单
```
@authorized {
    header X-API-Key "key-001"
    header X-API-Key "key-002"
}
@unauthorized { not @authorized }
respond @unauthorized "Unauthorized" 401
```

## 适用场景

- ✅ 服务间 API 调用（内部微服务）
- ✅ 简单 Webhook 接收端点
- ✅ 开发/测试环境快速保护
- ❌ 需要用户身份/权限细分的场景 → 使用 JWT 或 [[forward-authentication|外部认证]]

## 相关概念

- [[reverse-proxy-authentication]] — 反向代理层认证
- [[forward-authentication]] — 复杂认证委托
- [[caddy-reverse-proxy-auth]] — Caddy 配置方案