API 인증

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

인증 흐름

---

토큰 발급 (로그인)

로그인은 이메일과 비밀번호로 수행합니다.

cURL

curl -X POST https://{host}/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "your-password"
  }'

Python

import requests

response = requests.post(
    "https://{host}/api/v1/auth/login",
    json={
        "email": "you@example.com",
        "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({
    email: "you@example.com",
    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에 접근할 수 있습니다. 두 가지 발급 경로가 있습니다.

• 본인 토큰: POST /api/v1/auth/tokens — 로그인한 사용자가 자신의 권한으로 토큰을 발급합니다.
• 관리자 발급: POST /api/v1/admin/tokens — 관리자가 발급합니다(관리자 권한 필요).

# 본인 권한으로 서비스 토큰 발급
curl -X POST https://{host}/api/v1/auth/tokens \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "data-pipeline-bot",
    "description": "자동화 파이프라인 연동용"
  }'

발급받은 서비스 토큰은 일반 access_token과 동일하게 Authorization: Bearer 헤더로 사용합니다.

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

팁

발급·조회·폐기 엔드포인트의 정확한 요청/응답 스키마는 자동 생성 API 레퍼런스의 auth/admin 토큰 항목을 참고하세요.

---

Knowledge Chat API 인증

RAG 기반 Knowledge Chat은 OpenAI Chat Completions와 호환되는 엔드포인트({knowledge_base}/v1/chat/completions)를 제공합니다. 이 엔드포인트는 핵심 API(/api/v1)와 별도의 서비스 주소에서 동작하며, 동일한 JWT 토큰을 api_key로 전달합니다.

from openai import OpenAI

client = OpenAI(
    base_url="https://{knowledge_base}/v1",   # Knowledge(RAG) 서비스 주소
    api_key="{access_token}",
)

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

---

일반적인 인증 오류

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

---

다음 단계

• 도구별 호출 패턴 → API 클라이언트 도구
• 전체 엔드포인트 스펙 → API 레퍼런스