API Documentation

Overview

The SaaS Auth API provides a complete authentication and authorization solution for SaaS applications. It includes user management, role-based access control, API key management, and more.

Features

• User registration and authentication
• JWT-based authentication with refresh tokens
• Role-based access control (RBAC)
• API key management with permission system
• Rate limiting and request throttling
• Audit logging for security events
• Secure password management
• Email verification workflows
• Password reset functionality

API Endpoints

Authentication

Endpoint	Method	Description	Authentication
/api/v1/auth/register	POST	Register a new user	None
/api/v1/auth/login	POST	Authenticate a user	None
/api/v1/auth/refresh	POST	Refresh access token	None
/api/v1/auth/logout	POST	Logout (invalidate refresh token)	None
/api/v1/auth/logout-all	POST	Logout from all devices	JWT
/api/v1/auth/reset-password	POST	Request password reset	None
/api/v1/auth/reset-password/confirm	POST	Confirm password reset	None
/api/v1/auth/change-password	POST	Change user password	JWT
/api/v1/auth/verify-email	POST	Verify user email	None
/api/v1/auth/resend-verification	POST	Resend verification email	JWT

Users

Endpoint	Method	Description	Authentication	Authorization
/api/v1/users	GET	List all users	JWT	Admin role
/api/v1/users	POST	Create a new user	JWT	Admin role
/api/v1/users/me	GET	Get current user profile	JWT	Any authenticated user
/api/v1/users/me	PUT	Update current user profile	JWT	Any authenticated user
/api/v1/users/:id	GET	Get a user by ID	JWT	Admin role
/api/v1/users/:id	PUT	Update a user	JWT	Admin role
/api/v1/users/:id	DELETE	Delete a user	JWT	Admin role
/api/v1/users/:id/roles	GET	Get user roles	JWT	Admin role
/api/v1/users/:id/roles	POST	Add a role to user	JWT	Admin role
/api/v1/users/:id/roles/:roleId	DELETE	Remove a role from user	JWT	Admin role

Roles

Endpoint	Method	Description	Authentication	Authorization
/api/v1/roles	GET	List all roles	JWT	Any authenticated user
/api/v1/roles	POST	Create a new role	JWT	Admin role
/api/v1/roles/:id	GET	Get a role by ID	JWT	Any authenticated user
/api/v1/roles/:id	PUT	Update a role	JWT	Admin role
/api/v1/roles/:id	DELETE	Delete a role	JWT	Admin role
/api/v1/roles/:id/permissions	GET	Get role permissions	JWT	Any authenticated user
/api/v1/roles/:id/permissions	POST	Add a permission to role	JWT	Admin role
/api/v1/roles/:id/permissions/:permissionId	DELETE	Remove a permission from role	JWT	Admin role

Permissions

Endpoint	Method	Description	Authentication	Authorization
/api/v1/permissions	GET	List all permissions	JWT	Any authenticated user
/api/v1/permissions	POST	Create a new permission	JWT	Admin role
/api/v1/permissions/:id	GET	Get a permission by ID	JWT	Any authenticated user
/api/v1/permissions/:id	PUT	Update a permission	JWT	Admin role
/api/v1/permissions/:id	DELETE	Delete a permission	JWT	Admin role

API Keys

Endpoint	Method	Description	Authentication	Authorization
/api/v1/api-keys	GET	List user’s API keys	JWT	Any authenticated user
/api/v1/api-keys	POST	Create a new API key	JWT	Any authenticated user
/api/v1/api-keys/:id	GET	Get an API key by ID	JWT	Owner of the API key
/api/v1/api-keys/:id	PUT	Update an API key	JWT	Owner of the API key
/api/v1/api-keys/:id	DELETE	Delete an API key	JWT	Owner of the API key
/api/v1/api-keys/:id/permissions	GET	Get API key permissions	JWT	Owner of the API key
/api/v1/api-keys/:id/permissions	POST	Add a permission to API key	JWT	Owner of the API key
/api/v1/api-keys/:id/permissions	PUT	Set all permissions for API key	JWT	Owner of the API key
/api/v1/api-keys/:id/permissions/:permissionId	DELETE	Remove a permission from API key	JWT	Owner of the API key

Health Check

Endpoint	Method	Description	Authentication
/health	GET	Health check endpoint	None

Authentication Methods

The API supports two authentication methods:

1. JWT Authentication - Bearer token in the Authorization header

   Authorization: Bearer {your_access_token}

2. API Key Authentication - API key in the X-API-Key header

   X-API-Key: {your_api_key}

Request & Response Examples

User Registration

Request:

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

{
  "email": "[email protected]",
  "password": "securepassword123",
  "first_name": "John",
  "last_name": "Doe"
}

Response:

{
  "message": "User registered successfully",
  "user_id": "5f8d0d55-8b96-4536-8c34-781a9a3e9a9b"
}

User Login

Request:

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

{
  "email": "[email protected]",
  "password": "securepassword123"
}

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 900
}

Creating an API Key

Request:

POST /api/v1/api-keys
Content-Type: application/json
Authorization: Bearer {your_access_token}

{
  "name": "My API Key",
  "expires_at": "2025-12-31T23:59:59Z"
}

Response:

{
  "id": "8a7b6c5d-4e3f-2a1b-0c9d-8e7f6a5b4c3d",
  "user_id": "5f8d0d55-8b96-4536-8c34-781a9a3e9a9b",
  "name": "My API Key",
  "key": "sk-Avery1LongRandomAPIKeyStringThatShouldBeStoredSafely",
  "prefix": "sk-Avery",
  "is_active": true,
  "expires_at": "2025-12-31T23:59:59Z",
  "created_at": "2023-06-01T12:34:56Z",
  "updated_at": "2023-06-01T12:34:56Z"
}

Error Responses

The API returns consistent error responses in the following format:

{
  "error": "Description of the error",
  "status": 400
}

For validation errors, the response includes field-specific errors:

{
  "error": "Validation failed",
  "fields": {
    "email": "must be a valid email address",
    "password": "must be at least 8 characters"
  }
}

Rate Limiting

The API implements rate limiting to protect against abuse. Rate limits are applied per user or IP address.

When rate limits are exceeded, the API returns a 429 Too Many Requests response with headers indicating the limit and when the limit resets:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1623456789

Pagination

List endpoints support pagination with the following query parameters:

• page - Page number (default: 1)
• per_page - Number of items per page (default: 20, max: 100)

Paginated responses include metadata:

{
  "users": [...],
  "total_count": 42,
  "page_count": 3,
  "page": 1,
  "page_size": 20
}