概述

API Key 认证失败（401/403 错误）是开发中常见的问题。本文提供系统性的排查流程和解决方案。

错误类型

排查流程

1. 检查 Key 是否存在

import os

api_key = os.getenv("API_KEY")
if not api_key:
    raise ValueError("API_KEY environment variable not set")

# 检查格式
print(f"Key length: {len(api_key)}")
print(f"Key prefix: {api_key[:10]}...")

2. 检查 Header 格式

import httpx

# 正确格式
headers = {
    "Authorization": f"Bearer {api_key}"  # 注意大写 Bearer
}

# 错误示例
# "bearer {api_key}"  # 小写 bearer
# "Token {api_key}"   # 错误的 Token 前缀
# f"Bearer{api_key}"  # 缺少空格

response = httpx.get(
    "https://api.example.com/data",
    headers=headers
)

3. 检查 Key 有效期

# 检查环境变量是否设置了过期时间
import os
from datetime import datetime, timedelta

key_created = os.getenv("KEY_CREATED_AT")
if key_created:
    created = datetime.fromisoformat(key_created)
    expiry = created + timedelta(days=90)
    if datetime.now() > expiry:
        print("API Key has expired!")
        print(f"Expired on: {expiry}")

4. 检查 Key 权限

# 使用 API 查看 Key 的权限范围
response = httpx.get(
    "https://api.example.com/api-keys/current",
    headers={"Authorization": f"Bearer {api_key}"}
)
print(response.json())
# 检查返回的 scopes/permissions 字段

常见问题

Q1: Bearer 和 Token 有什么区别？

Bearer 是 OAuth 2.0 标准格式，大多数 API 使用 Bearer {key}。Token 前缀通常用于旧的认证系统。

Q2: API Key 和 Access Token 有什么区别？

API Key 是静态密钥，长期有效。Access Token 是 OAuth 流程颁发的短期令牌，需要定期刷新。

Q3: 如何安全存储 API Key？

1. 使用环境变量而非硬编码
2. 使用密钥管理服务（如 AWS Secrets Manager）
3. 不要提交到代码仓库

最佳实践

# .env 文件（不要提交到 git）
API_KEY=your-api-key-here

# Python 代码
from dotenv import load_dotenv
load_dotenv()

api_key = os.getenv("API_KEY")
if not api_key:
    raise ValueError("Missing API_KEY")

# 使用前验证
if len(api_key) < 20:
    raise ValueError("Invalid API_KEY format")

参考资料

• OAuth 2.0 Bearer Token Usage
• HTTP 认证框架