Auth Documentation

Welcome to the official documentation for Auth, an enterprise-grade authorization system with role-based access control (RBAC), audit logging, encryption, and high availability features.

Tests Python Version License

Getting Started

User Guide

Deployment

API Reference

Additional Resources

About Auth

Auth is a comprehensive, production-ready authorization system designed for enterprise applications. It provides a robust foundation for managing user permissions, roles, and access control with both REST API and Python library interfaces.

Key Features

Core Features:

  • Role-Based Access Control (RBAC) - Hierarchical user, role, and permission management

  • Multiple Storage Backends - SQLite (development) and PostgreSQL (production)

  • Dual Interface - REST API and Python library

  • JWT Authentication - Secure token-based authentication

  • Data Encryption - Optional encryption for sensitive data fields

  • Audit Logging - Comprehensive audit trail for compliance

  • Workflow Permissions - APScheduler integration for workflow permission checking

Security Features:

  • UUID4-based client authentication

  • JWT token-based authorization

  • Deterministic field-level encryption (AES-256-CTR) - Queryable encrypted data

  • Comprehensive audit logging with timestamps

  • Input validation and sanitization

  • CORS configuration

Production Features:

  • Connection pooling with retry logic

  • Circuit breaker pattern for fault tolerance

  • Configurable CORS settings

  • Health check endpoint

  • Consistent API response formats

  • Extensive test coverage (152 tests)

Quick Example

Python Library Usage:

import uuid
from auth import Authorization

# Generate a client key
client_key = str(uuid.uuid4())

# Create authorization instance
auth = Authorization(client_key)

# Create roles
auth.add_role('admin', description='Administrator role')
auth.add_role('editor', description='Content editor role')

# Add permissions
auth.add_permission('admin', 'manage_users')
auth.add_permission('editor', 'edit_content')

# Add users to roles
auth.add_membership('alice@example.com', 'admin')
auth.add_membership('bob@example.com', 'editor')

# Check permissions
if auth.user_has_permission('alice@example.com', 'manage_users'):
    print("Alice can manage users")

REST API Usage:

# Create a role
CLIENT_KEY=$(uuidgen)
curl -X POST \
  http://localhost:5000/api/role/admin \
  -H "Authorization: Bearer $CLIENT_KEY"

# Add permission to role
curl -X POST \
  http://localhost:5000/api/permission/admin/manage_users \
  -H "Authorization: Bearer $CLIENT_KEY"

# Check user permission
curl -X GET \
  http://localhost:5000/api/has_permission/alice@example.com/manage_users \
  -H "Authorization: Bearer $CLIENT_KEY"

Why Auth?

Production-Ready

Built with enterprise requirements in mind, featuring comprehensive error handling, audit logging, and extensive test coverage.

Flexible Deployment

Use as a standalone REST API service or integrate directly into your Python application as a library.

Security First

Multiple layers of security including JWT authentication, field-level encryption, and comprehensive audit trails.

High Availability

Circuit breaker pattern, connection pooling, and PostgreSQL support for production deployments.

Developer Friendly

Clean API design, comprehensive documentation, and extensive examples make integration straightforward.

Use Cases

  • Web Applications - Secure user access control and role management

  • Microservices - Centralized authorization service for distributed systems

  • Workflow Engines - APScheduler integration for workflow-based permissions

  • Compliance - Comprehensive audit logging for regulatory requirements

  • Multi-tenant Applications - Client-based isolation and permission management

Indices and Tables