API 키 관리

개요

API 키는 DocMap API에 프로그래밍 방식으로 접근할 수 있게 해줍니다. 각 키는 dm_live_ 접두사가 붙은 72자 토큰이며, Authorization 헤더에 Bearer 토큰으로 전달합니다.

주요 사항:

계정당 최대 10개의 활성 키
형식: dm_live_ 다음에 64개의 랜덤 16진수 문자 (총 72자)
키는 저장 전에 해시 처리됩니다 -- 원시 키는 생성 시 한 번만 표시됩니다
키에 만료 날짜를 설정하거나 만료 없이 설정할 수 있습니다

키 생성

대시보드에서

DocMap 대시보드에서 설정 > API 키로 이동합니다
API 키 생성을 클릭합니다
설명적인 이름을 입력합니다 (예: "프로덕션 서버", "CI/CD 파이프라인")
만료 기간을 선택합니다
표시된 키를 즉시 복사합니다 -- 다시 표시되지 않습니다

API에서

기존 API 키로 인증하여 프로그래밍 방식으로 키를 생성할 수도 있습니다:

curlTypeScriptPython

bash

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`	만료 없음

응답에는 원시 키와 키 메타데이터가 모두 포함됩니다:

json

{
  "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 키를 조회합니다:

curlTypeScriptPython

bash

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자)만 표시됩니다:

json

{
  "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 키를 교체하려면 다음 단계를 따르세요:

새 키 생성 -- 대체 키임을 나타내는 설명적인 이름을 지정합니다
시스템 업데이트 -- 환경 변수, 시크릿 관리자, CI/CD를 새 키로 업데이트합니다
검증 -- 테스트 API 호출로 새 키가 올바르게 작동하는지 확인합니다
이전 키 폐기 -- 모든 시스템이 업데이트된 후 이전 키를 폐기합니다

typescript

// 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 키를 폐기합니다. 키는 즉시 작동을 중단합니다.

curlTypeScriptPython

bash

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 타임스탬프를 추적합니다. 목록 엔드포인트를 사용하여 키가 마지막으로 활성화된 시기를 모니터링하세요:

typescript

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". 이렇게 하면 키가 유출되었을 때 어떤 키를 폐기해야 하는지 쉽게 식별할 수 있습니다.
만료 날짜를 설정하세요. never보다 90d 또는 1y를 선호하세요. 만료되는 키는 정기적인 교체를 강제하여 키가 유출된 경우 노출 기간을 제한합니다.
환경을 분리하세요. 개발, 스테이징, 프로덕션에 서로 다른 키를 사용하세요. 환경 간에 키를 공유하지 마세요.
정기적으로 교체하세요. 만료 날짜가 있더라도 특히 팀원이 떠나거나 인프라가 변경된 후에는 선제적으로 키를 교체하세요.
원시 키를 로그에 기록하지 마세요. 애플리케이션 로그, 오류 보고서 또는 콘솔 출력에 API 키를 출력하지 마세요. 로그에서 키를 참조해야 할 때는 prefix 필드를 사용하세요.
환경 변수를 사용하세요. 키를 환경 변수 또는 시크릿 관리자에 저장하세요. 소스 코드에 하드코딩하거나 버전 관리에 커밋하지 마세요.

API 키 관리 ​

개요 ​

키 생성 ​

대시보드에서 ​

API에서 ​

키 목록 조회 ​

키 교체 ​

키 폐기 ​

사용 모니터링 ​

모범 사례 ​

API 키 관리

개요

키 생성

대시보드에서

API에서

키 목록 조회

키 교체

키 폐기

사용 모니터링

모범 사례