Authentication API

User authentication and token management endpoints

Overview

The Authentication API handles user login, registration, token refresh, and session management.

Base Path: /auth

Endpoints

Login

POST /auth/login

Request Body:

{
  "email": "[e-mail]",
  "password": "your-password"
}

Response (200 OK):

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 86400,
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "[e-mail]",
    "name": "John Doe",
    "firm_id": "770e8400-e29b-41d4-a716-446655440222",
    "role": "admin"
  }
}

Register

POST /auth/register

Request Body:

{
  "email": "[e-mail]",
  "password": "secure-password",
  "name": "Jane Smith",
  "firm_name": "NewCo Ventures"
}

Response (201 Created):

{
  "user": {
    "id": "uuid",
    "email": "[e-mail]",
    "name": "Jane Smith"
  },
  "message": "Account created successfully. Please check your email to verify."
}

Refresh Token

POST /auth/refresh

Headers:

Authorization: Bearer {current_token}

Response:

{
  "access_token": "new-jwt-token",
  "token_type": "bearer",
  "expires_in": 86400
}

Logout

POST /auth/logout

Response:

{
  "message": "Logged out successfully"
}

Get Current User

GET /auth/me

Headers:

Authorization: Bearer {token}

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "[e-mail]",
  "name": "John Doe",
  "firm_id": "770e8400-e29b-41d4-a716-446655440222",
  "firm_name": "Acme Ventures",
  "role": "admin",
  "created_at": "2024-01-01T00:00:00Z"
}

Token Structure

JWT Payload

{
  "sub": "550e8400-e29b-41d4-a716-446655440000",
  "email": "[e-mail]",
  "firm_id": "770e8400-e29b-41d4-a716-446655440222",
  "role": "admin",
  "iat": 1706000000,
  "exp": 1706086400
}

Error Codes

Code	Error	Description
400	invalid_credentials	Email or password incorrect
400	email_already_exists	Email already registered
401	token_expired	JWT token has expired
401	invalid_token	JWT token is malformed or invalid
422	validation_error	Request body validation failed

Frontend Integration

// Login
async function login(email: string, password: string) {
  const response = await fetch('/auth/login', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ email, password })
  })

  const data = await response.json()

  // Store token
  localStorage.setItem('access_token', data.access_token)

  return data.user
}

// Auto-refresh before expiration
useEffect(() => {
  const refreshInterval = setInterval(async () => {
    const newToken = await refreshToken()
    localStorage.setItem('access_token', newToken)
  }, 23 * 60 * 60 * 1000) // 23 hours

  return () => clearInterval(refreshInterval)
}, [])

Next Steps

Authentication Flow

Complete auth architecture

Backend Auth

JWT middleware implementation

Security Guide

Security best practices