Skip to main content

​
Overview

The Authentication API handles user login, registration, token refresh, and session management. Base Path: /auth

​
Endpoints

​
Login

POST /auth/login
Request Body: 
{
  "email": "user@example.com",
  "password": "your-password"
}
Response (200 OK): 
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 86400,
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "name": "John Doe",
    "firm_id": "770e8400-e29b-41d4-a716-446655440222",
    "role": "admin"
  }
}

​
Register

POST /auth/register
Request Body: 
{
  "email": "newuser@example.com",
  "password": "secure-password",
  "name": "Jane Smith",
  "firm_name": "NewCo Ventures"
}
Response (201 Created): 
{
  "user": {
    "id": "uuid",
    "email": "newuser@example.com",
    "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": "user@example.com",
  "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": "user@example.com",
  "firm_id": "770e8400-e29b-41d4-a716-446655440222",
  "role": "admin",
  "iat": 1706000000,
  "exp": 1706086400
}

​
Error Codes

CodeErrorDescription
400invalid_credentialsEmail or password incorrect
400email_already_existsEmail already registered
401token_expiredJWT token has expired
401invalid_tokenJWT token is malformed or invalid
422validation_errorRequest 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