Authentication API

API for user authentication and token management.

Overview

D.Hub uses a JWT (JSON Web Token) based authentication system. It provides both security and convenience through a dual token structure with Access Token and Refresh Token.

Authentication Flow

1. Login → Access Token issued + Refresh Token (cookie)
2. API request → Include Access Token in Authorization header
3. Access Token expired → Renew via Refresh endpoint
4. Refresh Token expired → Re-login required

Endpoints

POST /api/v1/auth/login

Performs user login and issues an Access Token.

Request Body

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

Field	Type	Required	Description
email	string	Yes	User email
password	string	Yes	Password

Response

200 OK

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

Field	Type	Description
access_token	string	JWT Access Token
token_type	string	Token type (always "bearer")

note

On successful login, a Refresh Token is automatically set as an HTTP-Only cookie.

Error Responses

Status Code	Description
401 Unauthorized	Invalid email or password

---

POST /api/v1/auth/logout

Terminates the current session and deletes the Refresh Token cookie.

Response

200 OK

{
  "message": "Logged out successfully"
}

---

POST /api/v1/auth/refresh

Issues a new Access Token using the Refresh Token.

info

The Refresh Token is automatically read from the cookie. No separate Request Body is required.

Response

200 OK

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

Error Responses

Status Code	Description
401 Unauthorized	Refresh Token is missing or invalid

---

GET /api/v1/auth/me

Retrieves the currently authenticated user's information.

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	User unique ID
email	string	User email
name	string	User name
is_active	boolean	Active status
provider	string	Auth provider (local, ldap, oidc)
roles	array	User role list
created_at	string	Account creation time (ISO 8601)

Error Responses

Status Code	Description
401 Unauthorized	Invalid Access Token

Usage Examples

cURL

# Login
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

# Get user info
curl https://api.dhub.io/api/v1/auth/me \
  -H "Authorization: Bearer <access_token>"

# Refresh token
curl -X POST https://api.dhub.io/api/v1/auth/refresh \
  -b cookies.txt

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

JavaScript

// Login
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'  // include cookies
});
const { access_token } = await response.json();

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

Token Expiration Times

Token Type	Default Expiration
Access Token	30 minutes
Refresh Token	7 days

warning

Access Tokens should not be stored on the client side. They may be vulnerable to XSS attacks. It is recommended to keep them only in memory and renew with the Refresh Token as needed.