创建 API 密钥

POST /v1/api-keys

创建新的 API 密钥用于 DocMap API 认证。每个用户最多可以拥有 10 个有效（未吊销）的 API 密钥。

试一试

在 Swagger UI 中交互式测试此端点。

需要认证

在 Authorization 头中包含您的 API 密钥。

请求

请求头

头	值	必需
Authorization	Bearer <token>	是
Content-Type	application/json	是

请求体

字段	类型	必需	描述
name	string	是	密钥的描述性标签（1--100 个字符）。
expiresIn	string	是	有效期："30d"、"60d"、"90d"、"1y" 或 "never"。

代码示例

curl

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

TypeScript

const apiKey = process.env.DOCMAP_API_KEY

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

const { data } = await response.json()

// IMPORTANT: Store the key immediately — it cannot be retrieved later
console.log('API Key:', data.key)
console.log('Key ID:', data.apiKey.id)

Python

import requests

api_key = "dm_live_abc123def456ghi789jkl012mno345"

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

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

# IMPORTANT: Store the key immediately — it cannot be retrieved later
print(f"API Key: {data['key']}")
print(f"Key ID: {data['apiKey']['id']}")

响应

状态码：201 Created

响应体包含在 data 对象中。

WARNING

原始密钥值仅在此响应中返回。请立即安全存储 -- 之后无法再次获取。

字段

字段	类型	描述
key	string	原始 API 密钥（例如 dm_live_abc123def456ghi789jkl012mno345）。仅显示一次。
apiKey	object	密钥元数据对象（详见下方）。

apiKey 对象：

字段	类型	描述
id	string	API 密钥的唯一标识符。
userId	string	拥有该密钥的用户 ID。
name	string	密钥的描述性标签。
prefix	string	密钥的前几个字符，用于识别（例如 dm_live_abc1）。
expiresAt	string | null	ISO 8601 过期时间戳，如果密钥永不过期则为 null。
lastUsedAt	string | null	密钥最后使用时间的 ISO 8601 时间戳。如果从未使用则为 null。
createdAt	string	密钥创建时间的 ISO 8601 时间戳。
revoked	boolean	密钥是否已被吊销。新创建的密钥始终为 false。

示例

{
  "data": {
    "key": "dm_live_r4nd0mK3yV4lu3x9w8v7u6t5s4q3p2n1m0l9k8j7",
    "apiKey": {
      "id": "ak_1a2b3c4d5e6f7g8h",
      "userId": "uid_a1b2c3d4e5f6",
      "name": "Production Server",
      "prefix": "dm_live_r4nd",
      "expiresAt": "2025-02-18T10:00:00.000Z",
      "lastUsedAt": null,
      "createdAt": "2024-11-20T10:00:00.000Z",
      "revoked": false
    }
  }
}

错误

状态码	错误码	描述
400	MAX_KEYS_REACHED	您已达到 10 个有效 API 密钥的上限。请先吊销现有密钥再创建新密钥。
401	UNAUTHORIZED	缺少、无效或已过期的 API 密钥/令牌。