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	해당 리소스에 대한 권한 없음	관리자에게 접근 권한 요청