Authentication API#

Base URL: /api/auth

Endpoints#

POST /register#

Create a new user account.

Request:

{
  "username": "johndoe",
  "email": "john@example.com",
  "password": "secretpassword"
}

Response (200):

{
  "userId": "uuid",
  "username": "johndoe",
  "accessToken": "jwt...",
  "refreshToken": "jwt..."
}

Errors:

• 400 - Validation error (username/email taken, weak password)

POST /login#

Authenticate with credentials.

Request:

{
  "username": "johndoe",
  "password": "secretpassword"
}

Response (200):

{
  "userId": "uuid",
  "username": "johndoe",
  "accessToken": "jwt...",
  "refreshToken": "jwt..."
}

Errors:

• 401 - Invalid credentials

POST /refresh#

Refresh access token.

Request:

{
  "refreshToken": "jwt..."
}

Response (200):

{
  "accessToken": "jwt...",
  "refreshToken": "jwt..."
}

Errors:

• 401 - Invalid or expired refresh token

POST /logout#

Invalidate refresh token.

Headers:

Authorization: Bearer <access_token>

Request:

{
  "refreshToken": "jwt..."
}

Response (204): No content

GET /profile#

Get current user profile.

Headers:

Authorization: Bearer <access_token>

Response (200):

{
  "userId": "uuid",
  "username": "johndoe",
  "email": "john@example.com",
  "createdAt": "2026-01-30T12:00:00Z"
}

Token Details#

Access Token (JWT)#

• Expires: 24 hours
• Payload: { userId, username }
• Required for all authenticated endpoints

Refresh Token (JWT)#

• Expires: 30 days
• Used to obtain new access tokens
• Stored in database for revocation