Authentication API¶

Complete guide to authentication endpoints.

Register¶

Create a new user account.

Request¶

POST /auth/register
Content-Type: application/json

{
  "email": "user@example.com",
  "username": "johndoe",
  "password": "SecureP@ssw0rd123!"
}

Response¶

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
    "user": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "user@example.com",
      "username": "johndoe",
      "emailVerified": false,
      "twoFactorEnabled": false,
      "createdAt": "2024-10-19T12:00:00.000Z",
      "updatedAt": "2024-10-19T12:00:00.000Z"
    }
  }
}

Errors¶

Password Requirements¶

• Minimum 8 characters
• At least one uppercase letter
• At least one lowercase letter
• At least one number
• At least one special character

Rate Limiting¶

• Limit: 5 requests per 15 minutes
• Identifier: IP address

Login¶

Authenticate a user and obtain tokens.

Without 2FA¶

POST /auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "SecureP@ssw0rd123!"
}

Response:

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
  }
}

With 2FA Enabled¶

POST /auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "SecureP@ssw0rd123!",
  "deviceToken": "optional_device_token_if_trusted"
}

Response (2FA Required):

{
  "success": true,
  "data": {
    "tempToken": "eyJhbGciOiJIUzI1NiIs...",
    "requires2FA": true,
    "availableMethods": ["totp", "sms", "email"]
  }
}

Response (Trusted Device):

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
  }
}

Next Steps After 2FA Required¶

1. For TOTP: User enters code from authenticator app → Call POST /2fa/verify
2. For SMS/Email: Request code → Call POST /2fa/send-code → Call POST /2fa/verify

Errors¶

Rate Limiting¶

• Limit: 5 requests per 15 minutes
• Identifier: IP address

Refresh Token¶

Obtain a new access token using a refresh token.

Request¶

POST /auth/refresh
Content-Type: application/json

{
  "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
}

Response¶

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
  }
}

Errors¶

Rate Limiting¶

• Limit: 10 requests per 15 minutes
• Identifier: User ID

Get Current User¶

Retrieve the authenticated user's profile.

Request¶

GET /auth/me
Authorization: Bearer <access_token>

Response¶

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "username": "johndoe",
    "emailVerified": true,
    "twoFactorEnabled": true,
    "createdAt": "2024-10-19T12:00:00.000Z",
    "updatedAt": "2024-10-19T12:00:00.000Z"
  }
}

Errors¶

Logout¶

End the current session and revoke the refresh token.

Request¶

POST /auth/logout
Authorization: Bearer <access_token>

Response¶

{
  "success": true,
  "data": {
    "message": "Logged out successfully"
  }
}

Errors¶

Revoke All Sessions¶

Logout from all devices by revoking all refresh tokens.

Request¶

POST /auth/revoke-sessions
Authorization: Bearer <access_token>

Response¶

{
  "success": true,
  "data": {
    "message": "All sessions revoked",
    "revokedCount": 5
  }
}

Use Cases¶

• User suspects account compromise
• Lost device
• Security precaution

Errors¶

Token Lifetimes¶

Security Best Practices¶

Client-Side¶

1. Store access token in memory only (React state, Vuex, etc.)
2. Store refresh token securely:
3. Web: HttpOnly cookie (server-side set)
4. Mobile: Secure keychain/keystore
5. Never in localStorage or sessionStorage
6. Clear tokens on logout
7. Implement token refresh before expiration

Server-Side¶

1. Use HTTPS only in production
2. Set HttpOnly, Secure, SameSite cookies for refresh tokens
3. Implement CSRF protection for cookie-based auth
4. Log all authentication events for audit trail

Example: Complete Login Flow¶

React Example¶

import axios from 'axios'

interface LoginResponse {
  accessToken?: string
  refreshToken?: string
  tempToken?: string
  requires2FA?: boolean
  availableMethods?: string[]
}

async function login(email: string, password: string): Promise<LoginResponse> {
  const { data } = await axios.post('/auth/login', { email, password })

  if (data.data.requires2FA) {
    // Store temp token
    sessionStorage.setItem('tempToken', data.data.tempToken)
    // Redirect to 2FA page
    return data.data
  }

  // Store tokens
  localStorage.setItem('accessToken', data.data.accessToken) // ⚠️ Not recommended
  // Better: Store in memory only
  return data.data
}

async function refreshAccessToken(refreshToken: string): Promise<string> {
  const { data } = await axios.post('/auth/refresh', { refreshToken })
  return data.data.accessToken
}

// Axios interceptor for auto-refresh
axios.interceptors.response.use(
  response => response,
  async error => {
    if (error.response?.status === 401 && error.config && !error.config._retry) {
      error.config._retry = true
      const refreshToken = getRefreshToken() // Your storage method
      const newAccessToken = await refreshAccessToken(refreshToken)
      error.config.headers.Authorization = `Bearer ${newAccessToken}`
      return axios(error.config)
    }
    return Promise.reject(error)
  }
)

Node.js Example¶

const axios = require('axios')

async function login(email, password) {
  try {
    const response = await axios.post('https://your-api.com/auth/login', {
      email,
      password
    })

    if (response.data.data.requires2FA) {
      console.log('2FA required:', response.data.data.availableMethods)
      return response.data.data
    }

    console.log('Login successful')
    return response.data.data
  } catch (error) {
    if (error.response?.status === 401) {
      console.error('Invalid credentials')
    } else if (error.response?.status === 429) {
      console.error('Too many login attempts. Please try again later.')
    }
    throw error
  }
}

Python Example¶

import requests

def login(email: str, password: str) -> dict:
    response = requests.post('https://your-api.com/auth/login', json={
        'email': email,
        'password': password
    })

    response.raise_for_status()
    data = response.json()['data']

    if data.get('requires2FA'):
        print(f"2FA required: {data['availableMethods']}")
        return data

    print("Login successful")
    return data

Related Endpoints¶

• Two-Factor Authentication - Setup and verify 2FA
• Password Reset - Reset forgotten password
• Email Verification - Verify email address

Rate Limits Summary¶

Next Steps¶

• Setup 2FA - Enable two-factor authentication
• Integration Guide - Integrate into your app
• Error Codes - Complete error reference