Authentication & System Roles

Relevant source files

The following files were used as context for generating this wiki page:

• api/auth.py
• api/routers/auth.py
• src/config/settings.py
• ARCHITECTURE.md
• AGENTS.md

The Authentication and System Roles module manages secure access to the Financial Asset Relationship Database API. It implements JSON Web Token (JWT) based authentication to protect sensitive endpoints, such as those related to asset management and system administration.

This system defines administrative roles and credentials that allow authorized users to perform restricted operations. The implementation relies on centralized configuration for security parameters, ensuring consistent enforcement across the production FastAPI backend.

Sources: ARCHITECTURE.md, AGENTS.md

Authentication Architecture

The system uses a centralized authentication layer built into the FastAPI backend. This layer handles user identity verification and token issuance.

Centralized Security Configuration

The application centralizes security parameters within the Settings class. This configuration includes the signing key, token expiration durations, and default administrative credentials.

Parameter	Description	Source File
SECRET_KEY	The secret string used for signing JWTs.	src/config/settings.py
ADMIN_USERNAME	The default username for the system administrator.	src/config/settings.py
ADMIN_PASSWORD	The default password for the system administrator.	src/config/settings.py
ADMIN_DISABLED	Boolean flag to disable the administrator account.	src/config/settings.py

Sources: src/config/settings.py:25-31, AGENTS.md

Token Generation Flow

Authorized users obtain a JWT by providing valid credentials to the /token endpoint. The backend validates these credentials against configured settings or the database and returns a bearer token.

System Roles and Permissions

The system implements role-based access control, primarily focusing on Administrative access for sensitive management tasks.

Administrator Role

The Admin role is defined through environment variables or database seeding. Admins have the authority to access restricted endpoints, such as the rebuild-admin endpoints and the /api/users/me profile route.

Access Control Logic

The following diagram illustrates how the system gatekeeps protected resources using dependency injection in FastAPI.

Security Implementation Details

JWT Management

Authentication is stateless. The server does not store session data but verifies the SECRET_KEY signature on every incoming request containing a bearer token.

• Algorithm: The system typically uses HMAC SHA256 for signing.
• Payload: The token payload contains the user identity (sub) and expiration timestamp (exp).

Sources: api/auth.py, src/config/settings.py

User Seeding and Initialization

During backend startup, api/auth.py handles the seeding of initial user data if the database is empty. It uses the following hierarchy for admin identity:

1. ADMIN_USERNAME from environment/settings.
2. ADMIN_PASSWORD from environment/settings.
3. ADMIN_EMAIL and ADMIN_FULL_NAME for profile details.

Sources: api/auth.py, AGENTS.md

Summary

The Authentication & System Roles module provides a robust security framework for the Financial Asset Relationship Database. By leveraging JWTs and centralized configuration through src/config/settings.py, the system ensures that management operations remain restricted to authorized administrators. This architecture supports stateless scaling and consistent security enforcement across the production API.