Skip to main content

Authentication Service

Base path: /auth

Requires DB access to User records and uses secure password hashing and JWTs.

What this service does (plain English)

  • Create accounts, sign users in, and mint short-lived access tokens (plus refresh tokens)
  • Enforce strong password and email validation
  • Log security and performance events for auditability

How it works

  • Passwords are hashed (never stored in plain text)
  • On login, tokens carry minimal claims {sub, email, name}
  • A refresh token can be exchanged for a new pair when the access token expires

Endpoints

Register​

  • Method: POST /auth/register
  • Auth: Not required
  • Body:
{
  "email": "[email protected]",
  "name": "Ada Lovelace",
  "password": "P@ssw0rd!Strong"
}
  • 201 Response:
{
  "id": 123,
  "email": "[email protected]",
  "name": "Ada Lovelace",
  "is_active": true,
  "is_admin": false,
  "date_joined": "2025-02-05T12:34:56.000Z"
}
  • Errors:
    • 400: Invalid email format, weak password, or email already registered
    • 500: Registration failed

Login​

  • Method: POST /auth/login
  • Auth: Not required
  • Body:
{
  "email": "[email protected]",
  "password": "P@ssw0rd!Strong"
}
  • 200 Response:
{
  "access_token": "<JWT>",
  "refresh_token": "<JWT>"
}
  • Errors:
    • 400: Invalid email format
    • 401: Invalid credentials
    • 403: Inactive user
    • 500: Login failed

Refresh Token​

  • Method: POST /auth/login/refresh
  • Auth: Not required
  • Body:
{
  "refresh_token": "<JWT>"
}
  • 200 Response:
{
  "access_token": "<JWT>",
  "refresh_token": "<JWT>"
}
  • Errors:
    • 400: Missing/invalid refresh token
    • 401: Invalid refresh token
    • 500: Token refresh failed