본문으로 건너뛰기
버전: v0.1.0

API 인증

D.Hub API는 JWT(JSON Web Token) 기반 인증을 사용합니다. 모든 API 요청에는 유효한 토큰이 필요하며, 토큰은 Authorization 헤더에 포함해야 합니다.

인증 흐름​

토큰 발급 (로그인)​

cURL​

curl -X POST https://{host}/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "your-username",
    "password": "your-password"
  }'

Python​

import requests

response = requests.post(
    "https://{host}/api/v1/auth/login",
    json={
        "username": "your-username",
        "password": "your-password",
    },
)

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

JavaScript​

const response = await fetch("https://{host}/api/v1/auth/login", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    username: "your-username",
    password: "your-password",
  }),
});

const { access_token, refresh_token } = await response.json();

응답​

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer"
}

API 호출​

발급받은 access_token을 Authorization 헤더에 포함하여 API를 호출합니다.

curl -X GET https://{host}/api/v1/datasets \
  -H "Authorization: Bearer {access_token}"
headers = {"Authorization": f"Bearer {access_token}"}

response = requests.get(
    "https://{host}/api/v1/datasets",
    headers=headers,
)
토큰 보안
  • 토큰을 소스 코드에 하드코딩하지 마세요.
  • 환경 변수나 비밀 관리 시스템을 통해 토큰을 관리하세요.
  • 클라이언트 측 코드에서는 토큰 노출에 주의하세요.

토큰 갱신​

access_token이 만료되면 refresh_token을 사용하여 새 토큰을 발급받을 수 있습니다.

curl -X POST https://{host}/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "{refresh_token}"
  }'
response = requests.post(
    "https://{host}/api/v1/auth/refresh",
    json={"refresh_token": refresh_token},
)

data = response.json()
access_token = data["access_token"]
refresh_token = data["refresh_token"]
갱신 토큰 교체

토큰 갱신 시 새로운 refresh_token도 함께 발급됩니다. 이전 refresh_token은 무효화되므로, 갱신 후 새 토큰으로 교체해야 합니다.

서비스 토큰​

자동화 스크립트, CI/CD 파이프라인, 외부 시스템 연동에는 서비스 토큰 사용을 권장합니다. 서비스 토큰은 만료 기한이 길고, 사용자 로그인 없이 API에 접근할 수 있습니다.

서비스 토큰 생성​

관리자 권한이 필요합니다.

curl -X POST https://{host}/api/v1/admin/service-tokens \
  -H "Authorization: Bearer {admin_access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "data-pipeline-bot",
    "description": "자동화 파이프라인 연동용"
  }'

서비스 토큰 사용​

발급받은 서비스 토큰은 일반 access_token과 동일한 방식으로 사용합니다.

curl -X GET https://{host}/api/v1/datasets \
  -H "Authorization: Bearer {service_token}"

Knowledge Chat API 인증​

Knowledge Chat API도 동일한 JWT 토큰을 사용합니다. OpenAI SDK를 사용할 경우 api_key 파라미터에 D.Hub 토큰을 전달합니다.

from openai import OpenAI

client = OpenAI(
    base_url="https://{host}/v1",
    api_key="{access_token}",
)

response = client.chat.completions.create(
    model="knowledge-chat",
    messages=[
        {"role": "user", "content": "서울시 교통 현황을 알려줘"}
    ],
)

일반적인 인증 오류​

상태 코드원인해결 방법
401 Unauthorized토큰이 없거나 만료됨로그인하여 새 토큰 발급 또는 토큰 갱신
401 Unauthorized토큰 형식이 잘못됨Bearer 접두사 포함 여부 확인
403 Forbidden해당 리소스에 대한 권한 없음관리자에게 접근 권한 요청