API Reference
This section provides detailed information about the key classes, methods, and parameters in the BOSA Authentication system.
Configuration
AuthenticationDbSettings
A singleton configuration class that holds authentication database settings and security parameters.
Parameters:
database_authentication_url: str | None — Database connection string for the authentication database.auth_secret_key: str | None — Secret key used for JWT token signing.auth_algorithm: str | None = "HS256" — Algorithm used for JWT token signing.auth_access_token_expire_minutes: int | None = 43200 — Token expiration time in minutes (default: 30 days).
initialize_authentication_db(settings: AuthenticationDbSettings)
initialize_authentication_db(settings: AuthenticationDbSettings) function initializes the authentication database, creating necessary tables if they don't exist.
Parameters:
settings: AuthenticationDbSettings — The authentication settings object.
Client Management
create_client_service
Service for creating new clients.
Methods:
create_client(name: str) -> ClientModel— Creates a new client with the given name. Returns the client model with API key.
verify_client_service
Service for verifying client API keys.
Methods:
verify_client_api_key(api_key: str) -> ClientModel— Verifies if an API key is valid. Returns the client model if valid, raises an exception otherwise.is_api_key_valid(api_key: str) -> bool— Checks if an API key is valid. Returns True if valid, False otherwise.
client_aware_service
Service for accessing client information from either an API key or client ID.
Methods:
get_client_by_api_key(api_key: str) -> ClientModel— Validates and retrieves a client using an API key.get_client_by_id(client_id: UUID) -> ClientModel— Retrieves a client directly by ID.
User Management
create_user_service
Service for creating new users within a client.
Methods:
create_user(client_api_key: str, identifier: str) -> UserModel— Creates a new user with the given identifier for the specified client. Returns the user model with secret.
get_user_service
Service for retrieving user information.
Methods:
get_user(client_api_key: str, user_id: UUID) -> UserModel— Gets a user by their ID.get_user_by_identifier(client_api_key: str, identifier: str) -> UserModel— Gets a user by their identifier.get_user_complete(api_key: str, user_id: UUID) -> UserComplete— Retrieves a complete user profile including third-party integrations. RaisesInvalidClientExceptionorUnauthorizedExceptionif validation fails.
authenticate_user_service
Service for authenticating users and generating tokens.
Methods:
authenticate_user(client_api_key: str, identifier: str, secret: str) -> TokenModel— Authenticates a user with the provided credentials and returns a token.
Token Management
create_token_service
Service for creating authentication tokens.
Methods:
create_token(user_id: UUID, client_id: UUID) -> TokenModel— Creates a new token for the specified user and client.
verify_token_service
Service for verifying authentication tokens.
Methods:
verify_token_and_get_user_id(client_api_key: str, token: str) -> UUID— Verifies a token and returns the associated user ID if valid.
revoke_token_service
Service for revoking authentication tokens.
Methods:
revoke_token(client_api_key: str, token: str) -> bool— Revokes a token. Returns True if the token was successfully revoked.
Third-Party Integration Management
third_party_integration_service
Methods:
create_integration(integration: ThirdPartyIntegrationAuth) -> ThirdPartyIntegrationAuth— Creates a new third-party integration. Returns the created integration.get_integration(client_id: UUID, user_id: UUID, connector: str) -> ThirdPartyIntegrationAuth | None— Gets an integration by client ID, user ID, and connector type. Returns the integration or None if not found.get_integrations(client_id: UUID, user_id: UUID) -> list[ThirdPartyIntegrationAuth]— Retrieves all integrations for the specified user and client.has_integration(client_id: UUID, user_id: UUID, connector: str) -> bool— Checks if an integration exists. Returns True if it exists, False otherwise.delete_integration(client_id: UUID, user_id: UUID, connector: str) -> bool— Deletes an integration. Returns True if deleted, False otherwise.
Models
ClientModel
Represents a client organization.
Attributes:
id: UUID — Client unique identifier.name: str — Client name.api_key: str — Client API key (only shown once during creation).is_active: bool — Whether the client is active.created_at: datetime — Creation timestamp.
UserModel
Represents a user within a client.
Attributes:
id: UUID — User unique identifier.client_id: UUID — Associated client ID.identifier: str — User identifier (e.g., email).secret: str — User secret (only shown once during creation).is_active: bool — Whether the user is active.created_at: datetime — Creation timestamp.
TokenModel
Represents an authentication token.
Attributes:
token: str — The JWT token string.token_type: str — The token type (always "bearer").expires_at: int — Token expiration timestamp.
ThirdPartyIntegrationAuth
Represents a third-party integration.
Attributes:
id: UUID — Integration unique identifier.client_id: UUID — Associated client ID.user_id: UUID — Associated user ID.connector: str — Integration type (e.g., "github").auth_string: str — Authentication credentials for the service.user_identifier: str — User identifier in the third-party service.auth_scopes: List[str] — Scopes/permissions granted to the integration.
Last updated