20260514:增加新内容

concepts/api-key-authentication.md

@@ -0,0 +1,53 @@
+---
+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 配置方案