Authentication API

API for user authentication and token management.

Overview

D.Hub uses a JWT (JSON Web Token) based authentication system. The dual token structure with Access Token and Refresh Token provides both security and ease of use.

Authentication Flow

1. Login → Access Token issued + Refresh Token (cookie)
2. API Request → Include Access Token in Authorization header
3. Access Token expires → Refresh via Refresh endpoint
4. Refresh Token expires → 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

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

Error Responses

Status Code	Description
401 Unauthorized	Email or password is incorrect

---

POST /api/v1/auth/logout

Ends 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	Authentication provider (local, ldap, oidc)
roles	array	List of user roles
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 information
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 can be vulnerable to XSS attacks. It is recommended to keep them only in memory and refresh using the Refresh Token when needed.