身份认证

概述

所有 /v1/* 端点都需要通过 Authorization 头使用 Bearer 令牌进行认证：

Authorization: Bearer <token>

API 密钥

API 密钥是服务端和程序化使用的推荐认证方式。它们长期有效、易于管理，且不需要任何外部 SDK。

创建 API 密钥

您可以通过两种方式创建 API 密钥：

通过控制面板：

1. 前往 控制面板 > 设置 > API 密钥。
2. 点击 创建 API 密钥。
3. 输入描述性名称并选择有效期。
4. 立即复制密钥。

通过 API：

curl -X POST https://api.docmap.io/v1/api-keys \
  -H "Authorization: Bearer <existing-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Server",
    "expiresIn": "90d"
  }'

密钥格式

API 密钥格式如下：

dm_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

密钥长度为 72 个字符，始终以 dm_live_ 前缀开头。

有效期选项

创建密钥时，您可以选择以下有效期：

• 30 天
• 60 天
• 90 天
• 1 年
• 永不过期

WARNING

永不过期的密钥使用方便，但如果泄露则风险更高。请使用满足需求的最短有效期。

数量限制

每个账户最多可以拥有 10 个有效 API 密钥。吊销不再使用的密钥以释放名额。

请求示例

cURL

curl https://api.docmap.io/v1/extractions \
  -H "Authorization: Bearer dm_live_your_api_key"

TypeScript

const response = await fetch('https://api.docmap.io/v1/extractions', {
  headers: {
    'Authorization': `Bearer ${process.env.DOCMAP_API_KEY}`,
  },
})

错误响应

如果认证失败，API 将返回 401 Unauthorized 响应：

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired authentication token."
  }
}

常见原因：

• 缺少 Authorization 头
• 令牌格式错误（前缀或格式不正确）
• API 密钥已过期
• API 密钥已被吊销

安全最佳实践

DANGER

切勿在客户端代码、公开仓库或浏览器环境中暴露 API 密钥。API 密钥拥有对您账户 API 的完整访问权限，应视为机密信息。

遵循以下准则来保护您的 API 凭据安全：

1. 将密钥存储在环境变量中 -- 切勿在源代码中硬编码 API 密钥。使用环境变量或密钥管理器。

   # .env file (never commit this)
   DOCMAP_API_KEY=dm_live_your_api_key

   // Read from environment
   const apiKey = process.env.DOCMAP_API_KEY

2. 定期轮换密钥 -- 即使没有怀疑密钥泄露的理由，也应定期创建新密钥并淘汰旧密钥。

3. 立即吊销已泄露的密钥 -- 如果密钥意外暴露（例如提交到公开仓库），请立即在 控制面板 > 设置 > API 密钥 中吊销该密钥，并创建新的替代密钥。

4. 使用尽可能短的有效期 -- 选择在便利性和安全性之间取得平衡的有效期。对于大多数生产用例，90 天是一个合适的默认值。

5. 为不同环境使用不同的密钥 -- 为开发、预发布和生产环境分别创建密钥。这样可以限制单个密钥泄露时的影响范围，并使密钥轮换更容易，不会导致服务中断。

6. 将 .env 文件添加到 .gitignore -- 确保环境文件永远不会被提交到版本控制。

   # .gitignore
   .env
   .env.local
   .env.*.local