API 키 생성

POST /v1/api-keys

DocMap API 인증을 위한 새 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 키 / 토큰.