Skip to main content

AuthSec API Documentation

Welcome to the AuthSec API Documentation - your complete guide to implementing secure, multi-tenant authentication and authorization.

🚀 Quick Navigation​

New to AuthSec?​

Start here to understand the platform and build your first integration.

→ Introduction - Platform overview and architecture
→ Quickstart Guide - Your first auth flow in 10 minutes
→ Authentication Flows - Choose the right method

Core Functionality​

CategoryWhat You'll Learn
User ManagementCreate and manage admin users and end users
Multi-Factor AuthenticationWebAuthn, TOTP, and SMS verification
Authorization & Access ControlRoles, permissions, and RBAC

Advanced Features​

CategoryWhat You'll Learn
Advanced AuthenticationOIDC, SAML, device auth, and CIBA
Client ManagementOAuth client and application management
System & InfrastructureHealth monitoring and tenant management

📖 Documentation Structure​

graph LR
    Start[Getting Started] --> Core[Core Authentication]
    Core --> Users[User Management]
    Users --> MFA[Multi-Factor Auth]
    MFA --> AuthZ[Authorization]
    AuthZ --> Advanced[Advanced Auth]
    Advanced --> Integration[Integration]
    Integration --> System[System]
    
    style Start fill:#4A90E2
    style Core fill:#E24A4A
    style Users fill:#4AE290
    style MFA fill:#E2D44A

🔑 Key Concepts​

Multi-Tenancy​

AuthSec isolates data by tenant with separate databases. Each API request requires a tenant_id to specify which tenant's data to access.

Admin vs End Users​

  • Admin Users: Global administrators who manage tenants and system configuration
  • End Users: Tenant-specific users who access applications

Authentication vs Authorization​

  • Authentication: Verifying user identity (login, MFA)
  • Authorization: Determining what authenticated users can access (RBAC, permissions)

🎯 Common Use Cases​

Basic Web Application Login​

  1. Create users
  2. Implement basic login
  3. Validate tokens

Adding Two-Factor Authentication​

  1. Start with basic login
  2. Add TOTP or WebAuthn
  3. Enforce MFA for users

Enterprise SSO Integration​

  1. Configure SAML or OIDC
  2. Set up directory sync
  3. Implement role mapping

Mobile App Authentication​

  1. Implement basic login
  2. Add WebAuthn biometrics
  3. Manage token refresh

🌐 API Endpoints​

Base URLs​

Development:

https://dev.api.authsec.dev

Production:

https://api.authsec.dev

Interactive Documentation​

Each service provides Swagger/ReDoc interfaces:

🛠️ SDKs​

Python​

pip install authsec-sdk
from authsec import AuthSecClient

client = AuthSecClient(base_url="https://dev.api.authsec.dev")
client.login("[email protected]", "password")
users = client.users.list()

TypeScript​

npm install @authsec/sdk
import { AuthSecClient } from '@authsec/sdk';

const client = new AuthSecClient({
  baseUrl: 'https://dev.api.authsec.dev'
});

await client.login('[email protected]', 'password');
const users = await client.users.list();

📚 Documentation by Service​

User Flow API (v4.0.0)​

Multi-tenant user management and authentication endpoints.

Key Sections:

Auth Manager API (v1.1.0)​

JWT token generation, validation, and authorization.

Key Sections:

WebAuthn Service API (v2.0)​

Multi-factor authentication with WebAuthn, TOTP, and SMS.

Key Sections:

Client Management API (v0.4.0)​

OAuth 2.0 client management for application integrations.

Key Sections:

🔒 Security & Best Practices​

[!IMPORTANT] Always use HTTPS - All API requests must use HTTPS. HTTP requests will be rejected.

[!WARNING] Token Security - Never store JWT tokens in local storage or URL parameters. Use secure, httpOnly cookies or secure device storage.

Key Security Practices:

  • Validate all user input before API calls
  • Implement proper error handling
  • Use MFA for sensitive operations
  • Rotate tokens regularly (default expiry: 1 hour)
  • Follow principle of least privilege for RBAC

See API Conventions for detailed best practices.

📊 Authentication Flow Comparison​

FlowSecurityComplexityBest For
Basic Login⭐⭐⭐⭐Internal tools, development
TOTP MFA⭐⭐⭐⭐⭐⭐Most applications
WebAuthn⭐⭐⭐⭐⭐⭐⭐⭐High-security apps
SAML SSO⭐⭐⭐⭐⭐⭐⭐⭐Enterprise B2B
CIBA⭐⭐⭐⭐⭐⭐⭐⭐⭐Banking, finance

Full comparison: Authentication Flows Guide

🆘 Need Help?​

I want to...​

Authenticate a user → Quickstart Guide
Add MFA → Multi-Factor Authentication
Set up roles and permissions → Authorization & Access Control
Integrate social login → OIDC & SSO
Understand API patterns → API Conventions
Debug an error → Check API Conventions - Error Handling

Troubleshooting​

401 Unauthorized: Token missing or invalid → Auth Manager Reference
403 Forbidden: Insufficient permissions → Authorization
404 Not Found: Check endpoint path and resource existence
429 Rate Limited: Implement retry logic → API Conventions

Ready to begin? Start with the Quickstart Guide →