Authentication API

사용자 인증 및 토큰 관리를 위한 API입니다.

개요

D.Hub는 JWT(JSON Web Token) 기반의 인증 시스템을 사용합니다. Access Token과 Refresh Token의 이중 토큰 구조로 보안성과 사용 편의성을 모두 제공합니다.

인증 흐름

1. 로그인 → Access Token 발급 + Refresh Token (쿠키)
2. API 요청 → Authorization 헤더에 Access Token 포함
3. Access Token 만료 → Refresh 엔드포인트로 갱신
4. Refresh Token 만료 → 재로그인 필요

엔드포인트

POST /api/v1/auth/login

사용자 로그인을 수행하고 Access Token을 발급합니다.

Request Body

{
  "email": "user@example.com",
  "password": "your-password"
}

Field	Type	Required	Description
email	string	Yes	사용자 이메일
password	string	Yes	비밀번호

Response

200 OK

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

Field	Type	Description
access_token	string	JWT Access Token
token_type	string	토큰 타입 (항상 "bearer")

노트

로그인 성공 시 Refresh Token이 HTTP-Only 쿠키로 자동 설정됩니다.

Error Responses

Status Code	Description
401 Unauthorized	이메일 또는 비밀번호가 올바르지 않음

---

POST /api/v1/auth/logout

현재 세션을 종료하고 Refresh Token 쿠키를 삭제합니다.

Response

200 OK

{
  "message": "Logged out successfully"
}

---

POST /api/v1/auth/refresh

Refresh Token을 사용하여 새로운 Access Token을 발급받습니다.

정보

Refresh Token은 쿠키에서 자동으로 읽어옵니다. 별도의 Request Body가 필요하지 않습니다.

Response

200 OK

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

Error Responses

Status Code	Description
401 Unauthorized	Refresh Token이 없거나 유효하지 않음

---

GET /api/v1/auth/me

현재 인증된 사용자의 정보를 조회합니다.

Headers

Authorization: Bearer <access_token>

Response

200 OK

{
  "id": "user-abc123",
  "email": "user@example.com",
  "name": "John Doe",
  "is_active": true,
  "provider": "local",
  "roles": ["user"],
  "created_at": "2024-01-15T09:00:00Z"
}

Field	Type	Description
id	string	사용자 고유 ID
email	string	사용자 이메일
name	string	사용자 이름
is_active	boolean	활성화 상태
provider	string	인증 제공자 (local, ldap, oidc)
roles	array	사용자 역할 목록
created_at	string	계정 생성 시간 (ISO 8601)

Error Responses

Status Code	Description
401 Unauthorized	유효하지 않은 Access Token

사용 예시

cURL

# 로그인
curl -X POST https://api.dhub.io/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "password123"}' \
  -c cookies.txt

# 사용자 정보 조회
curl https://api.dhub.io/api/v1/auth/me \
  -H "Authorization: Bearer <access_token>"

# 토큰 갱신
curl -X POST https://api.dhub.io/api/v1/auth/refresh \
  -b cookies.txt

# 로그아웃
curl -X POST https://api.dhub.io/api/v1/auth/logout \
  -b cookies.txt -c cookies.txt

JavaScript

// 로그인
const response = await fetch('/api/v1/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email: 'user@example.com', password: 'password123' }),
  credentials: 'include'  // 쿠키 포함
});
const { access_token } = await response.json();

// API 요청
const data = await fetch('/api/v1/datasets/', {
  headers: { 'Authorization': `Bearer ${access_token}` }
}).then(res => res.json());

토큰 만료 시간

Token Type	Default Expiration
Access Token	30분
Refresh Token	7일

경고

Access Token은 클라이언트 측에 저장하지 않아야 합니다. XSS 공격에 취약할 수 있습니다. 메모리에만 보관하고 필요 시 Refresh Token으로 갱신하는 것을 권장합니다.