API Reference

This section provides comprehensive API documentation for all public classes, functions, and modules in litestar-api-auth.

Note

All storage backends implement the APIKeyBackend protocol, ensuring consistent behavior across different providers.

Quick Navigation

Plugin & Configuration

  • APIAuthPlugin - Litestar plugin for API key authentication

  • APIAuthConfig - Plugin configuration

Guards

  • require_api_key() - Basic authentication guard

  • require_scope() - Single scope authorization guard

  • require_scopes() - Multiple scopes authorization guard

  • get_api_key_info() - Retrieve API key info from request

Types

  • APIKeyInfo - API key metadata container

  • APIKeyState - Key state enumeration (active, expired, revoked)

Schemas (msgspec)

  • CreateAPIKeyRequest - Key creation request

  • UpdateAPIKeyRequest - Key update request

  • APIKeyResponse - Key response (without raw key)

  • APIKeyCreatedResponse - Key creation response (with raw key)

  • APIKeyListResponse - Paginated key list response

Storage Backends

  • APIKeyBackend - Backend protocol

  • APIKeyInfo - Backend key info

  • MemoryBackend - In-memory (testing/development)

  • SQLAlchemyBackend - SQLAlchemy backend

  • APIKeyModel - SQLAlchemy ORM model (Advanced Alchemy)

  • APIKeyRepository - Async repository (Advanced Alchemy)

  • APIKeyService - Async service (Advanced Alchemy)

  • RedisBackend - Redis backend

Service Functions

  • generate_api_key() - Generate a new API key

  • hash_api_key() - Hash an API key for storage

  • verify_api_key() - Verify a key against its hash

  • extract_key_id() - Extract key ID from raw key

Exceptions

  • APIAuthError - Base exception

  • InvalidAPIKeyError - Invalid key error

  • APIKeyExpiredError - Expired key error

  • APIKeyRevokedError - Revoked key error

  • APIKeyNotFoundError - Key not found error

  • InsufficientScopesError - Missing scope error

  • ConfigurationError - Configuration error

Middleware & Controllers

  • APIKeyMiddleware - X-API-Key extraction middleware

  • APIKeyController - REST controller for key management