인증

개요

모든 /v1/* 엔드포인트는 Bearer 토큰을 사용하여 Authorization 헤더를 통한 인증이 필요합니다:

Authorization: Bearer <token>

API 키

API 키는 서버 측 및 프로그래밍 방식의 사용에 권장되는 인증 방법입니다. 수명이 길고 관리가 쉬우며 외부 SDK가 필요하지 않습니다.

API 키 생성

API 키는 두 가지 방법으로 생성할 수 있습니다:

대시보드를 통한 방법:

대시보드 > 설정 > API 키로 이동합니다.
API 키 생성을 클릭합니다.
설명적인 이름을 입력하고 만료 기간을 선택합니다.
키를 즉시 복사합니다.

API를 통한 방법:

bash

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 키를 보유할 수 있습니다. 슬롯을 확보하려면 사용하지 않는 키를 폐기하세요.

요청 예시

cURLTypeScript

bash

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 응답을 반환합니다:

json

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

일반적인 원인:

Authorization 헤더 누락
잘못된 형식의 토큰 (잘못된 접두사 또는 형식)
만료된 API 키
폐기된 API 키

보안 모범 사례

DANGER

API 키를 클라이언트 측 코드, 공개 저장소 또는 브라우저 환경에 절대 노출하지 마세요. API 키는 계정의 API에 대한 전체 액세스 권한을 부여하므로 비밀 정보로 취급해야 합니다.

API 자격 증명을 안전하게 유지하려면 다음 지침을 따르세요:

키를 환경 변수에 저장하세요 -- API 키를 소스 코드에 하드코딩하지 마세요. 환경 변수 또는 시크릿 관리자를 사용하세요.
bash
```
# .env file (never commit this)
DOCMAP_API_KEY=dm_live_your_api_key
```
typescript
```
// Read from environment
const apiKey = process.env.DOCMAP_API_KEY
```
정기적으로 키를 교체하세요 -- 유출이 의심되지 않더라도 정기적인 일정에 따라 새 키를 생성하고 이전 키를 폐기하세요.
유출된 키는 즉시 폐기하세요 -- 키가 실수로 노출된 경우 (예: 공개 저장소에 커밋) 대시보드 > 설정 > API 키에서 즉시 폐기하고 대체 키를 생성하세요.
가능한 가장 짧은 만료 기간을 사용하세요 -- 편의성과 보안의 균형을 맞추는 만료 기간을 선택하세요. 대부분의 프로덕션 사용 사례에서는 90일이 적절한 기본값입니다.
환경별로 별도의 키를 사용하세요 -- 개발, 스테이징, 프로덕션에 대해 별도의 키를 생성하세요. 이렇게 하면 하나의 키가 유출되었을 때 영향 범위를 제한하고 다운타임 없이 키를 교체하기 쉬워집니다.
.env 파일을 .gitignore에 추가하세요 -- 환경 파일이 버전 관리에 커밋되지 않도록 하세요.
gitignore
```
# .gitignore
.env
.env.local
.env.*.local
```

인증 ​

개요 ​

API 키 ​

API 키 생성 ​

키 형식 ​

만료 옵션 ​

제한 ​

요청 예시 ​

오류 응답 ​

보안 모범 사례 ​

인증

개요