管理 API 密钥

概述

API 密钥提供对 DocMap API 的程序化访问。每个密钥是一个 72 字符的令牌，以 dm_live_ 为前缀，作为 Bearer 令牌在 Authorization 头中传递。

关键信息：

• 每个账户最多 10 个有效密钥
• 格式：dm_live_ 后跟 64 个随机十六进制字符（共 72 个字符）
• 密钥在存储前会被哈希 -- 原始密钥仅在创建时显示一次
• 密钥可以设置过期日期或设为永不过期

创建密钥

通过控制面板

1. 在 DocMap 控制面板中导航到 设置 > API 密钥
2. 点击 创建 API 密钥
3. 输入描述性名称（例如"生产服务器"、"CI/CD 管道"）
4. 选择有效期
5. 立即复制显示的密钥 -- 之后不会再次显示

通过 API

您也可以通过已有的 API 密钥认证后以程序化方式创建密钥：

curl

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

TypeScript

const response = await fetch("https://api.docmap.io/v1/api-keys", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${existingApiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Production Server",
    expiresIn: "90d",
  }),
});

const { data } = await response.json();

// Store this immediately -- it will never be shown again
console.log("API Key:", data.key);
console.log("Key ID:", data.apiKey.id);

Python

import requests

response = requests.post(
    "https://api.docmap.io/v1/api-keys",
    headers={
        "Authorization": f"Bearer {existing_api_key}",
        "Content-Type": "application/json",
    },
    json={
        "name": "Production Server",
        "expiresIn": "90d",
    },
)

data = response.json()["data"]

# Store this immediately -- it will never be shown again
print("API Key:", data["key"])
print("Key ID:", data["apiKey"]["id"])

可用的 expiresIn 值：

值	有效期
30d	30 天
60d	60 天
90d	90 天
1y	1 年
never	永不过期

响应包含原始密钥和密钥元数据：

{
  "data": {
    "key": "dm_live_a1b2c3d4e5f6...",
    "apiKey": {
      "id": "key-abc123",
      "userId": "user_789",
      "name": "Production Server",
      "prefix": "dm_live_a1b2c3d4",
      "expiresAt": "2025-10-13T12:00:00.000Z",
      "lastUsedAt": null,
      "createdAt": "2025-07-15T12:00:00.000Z",
      "revoked": false
    }
  }
}

WARNING

响应中的 key 字段是原始 API 密钥唯一一次返回。请立即将其存储在安全位置（例如环境变量、密钥管理器）。如果丢失，您需要创建新密钥。

列出密钥

获取您账户的所有有效（未吊销）API 密钥：

curl

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

TypeScript

const response = await fetch("https://api.docmap.io/v1/api-keys", {
  headers: { Authorization: `Bearer ${apiKey}` },
});

const { data } = await response.json();

data.forEach((key) => {
  console.log(`${key.name} (${key.prefix}...) - Last used: ${key.lastUsedAt ?? "Never"}`);
});

Python

response = requests.get(
    "https://api.docmap.io/v1/api-keys",
    headers={"Authorization": f"Bearer {api_key}"},
)

for key in response.json()["data"]:
    last_used = key["lastUsedAt"] or "Never"
    print(f"{key['name']} ({key['prefix']}...) - Last used: {last_used}")

响应包含每个密钥的元数据，但不会包含完整密钥值 -- 只显示 prefix（前 16 个字符）：

{
  "data": [
    {
      "id": "key-abc123",
      "userId": "user_789",
      "name": "Production Server",
      "prefix": "dm_live_a1b2c3d4",
      "expiresAt": "2025-10-13T12:00:00.000Z",
      "lastUsedAt": "2025-07-15T14:30:00.000Z",
      "createdAt": "2025-07-15T12:00:00.000Z",
      "revoked": false
    }
  ]
}

轮换密钥

要在零停机时间内轮换 API 密钥，请按照以下步骤操作：

1. 创建新密钥，使用描述性名称标明它是替代密钥
2. 更新您的系统（环境变量、密钥管理器、CI/CD）以使用新密钥
3. 验证新密钥工作正常，进行一次测试 API 调用
4. 吊销旧密钥，在所有系统更新完成后

// Step 1: Create the new key
const createResponse = await fetch("https://api.docmap.io/v1/api-keys", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${currentApiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Production Server (rotated 2025-07)",
    expiresIn: "90d",
  }),
});

const { data: newKeyData } = await createResponse.json();
const newKey = newKeyData.key;

// Step 2: Verify the new key works
const testResponse = await fetch("https://api.docmap.io/v1/usage", {
  headers: { Authorization: `Bearer ${newKey}` },
});

if (testResponse.ok) {
  console.log("New key verified. Update your environment variables now.");

  // Step 3: Revoke the old key (after updating systems)
  // await fetch(`https://api.docmap.io/v1/api-keys/${oldKeyId}`, {
  //   method: "DELETE",
  //   headers: { Authorization: `Bearer ${newKey}` },
  // });
}

TIP

在过渡期间保持两个密钥都处于有效状态。只有在确认所有系统都使用新密钥后才吊销旧密钥。

吊销密钥

通过发送带有密钥 ID 的 DELETE 请求来吊销 API 密钥。密钥会立即停止工作。

curl

curl -X DELETE https://api.docmap.io/v1/api-keys/key-abc123 \
  -H "Authorization: Bearer dm_live_your_api_key"

TypeScript

const response = await fetch("https://api.docmap.io/v1/api-keys/key-abc123", {
  method: "DELETE",
  headers: { Authorization: `Bearer ${apiKey}` },
});

const result = await response.json();
console.log("Revoked:", result.success); // true

Python

response = requests.delete(
    "https://api.docmap.io/v1/api-keys/key-abc123",
    headers={"Authorization": f"Bearer {api_key}"},
)

print("Revoked:", response.json()["success"])  # True

WARNING

吊销是即时且永久的。任何使用已吊销密钥的请求都将收到 401 UNAUTHORIZED 错误。在吊销前请确保没有活跃系统依赖该密钥。

监控使用情况

每个 API 密钥会跟踪 lastUsedAt 时间戳，在密钥用于认证请求时自动更新。使用列表端点来监控密钥的最后活跃时间：

const response = await fetch("https://api.docmap.io/v1/api-keys", {
  headers: { Authorization: `Bearer ${apiKey}` },
});

const { data: keys } = await response.json();

// Find keys that haven't been used in over 30 days
const thirtyDaysAgo = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);

keys.forEach((key) => {
  if (!key.lastUsedAt || new Date(key.lastUsedAt) < thirtyDaysAgo) {
    console.log(`Key "${key.name}" (${key.prefix}...) is inactive — consider revoking it`);
  }
});

最佳实践

• 使用描述性名称。 以密钥的用途或环境命名："Production API"、"Staging"、"GitHub Actions CI"。这样在密钥泄露时能轻松识别应该吊销哪个密钥。

• 设置过期日期。 优先选择 90d 或 1y 而非 never。有过期日期的密钥会强制定期轮换，限制密钥泄露时的暴露窗口。

• 区分环境。 为开发、预发布和生产环境使用不同的密钥。切勿在不同环境间共享密钥。

• 定期轮换。 即使设置了过期日期，也应主动轮换密钥 -- 特别是在团队成员离职或基础设施变更后。

• 切勿记录原始密钥。 避免在应用日志、错误报告或控制台输出中打印 API 密钥。需要在日志中引用密钥时，请使用 prefix 字段。

• 使用环境变量。 将密钥存储在环境变量或密钥管理器中。切勿在源代码中硬编码或提交到版本控制。