Litestar-Users

https://mvbosch.github.io/litestar-users
Admin
Litestar-Users is an authentication, authorization and user management package for Litestar that...
Tokens:17,541
Snippets:158
Trust Score:8.3
Update:10 months ago
Show doc for...
Tokens:
Raw
### Minimal Litestar Users Configuration with SQLAlchemy

Source: https://mvbosch.github.io/litestar-users/usage/0-configuration

This example demonstrates a minimal setup for Litestar Users, including user model definition, DTOs, a custom user service, SQLAlchemy database configuration, and the Litestar application setup with the necessary plugins. It enables registration, verification, and login.

```python
from dataclasses import dataclass
from typing import Any

import uvicorn
from advanced_alchemy.base import UUIDBase
from litestar import Litestar
from advanced_alchemy.extensions.litestar.dto import SQLAlchemyDTO, SQLAlchemyDTOConfig
from advanced_alchemy.extensions.litestar.plugins import (
    SQLAlchemyAsyncConfig,
    SQLAlchemyInitPlugin,
)
from litestar.dto import DataclassDTO
from litestar.security.session_auth import SessionAuth

from litestar_users import LitestarUsersPlugin, LitestarUsersConfig
from litestar_users.adapter.sqlalchemy.mixins import SQLAlchemyUserMixin
from litestar_users.config import (
    AuthHandlerConfig,
    RegisterHandlerConfig,
    VerificationHandlerConfig,
)
from litestar_users.service import BaseUserService

ENCODING_SECRET = "1234567890abcdef"  # noqa: S105
DATABASE_URL = "sqlite+aiosqlite:////"


class User(UUIDBase, SQLAlchemyUserMixin):
    """User model."""


@dataclass
class UserRegistrationSchema:
    email: str
    password: str


class UserRegistrationDTO(DataclassDTO[UserRegistrationSchema]):
    """User registration DTO."""


class UserReadDTO(SQLAlchemyDTO[User]):
    config = SQLAlchemyDTOConfig(exclude={"password_hash"})


class UserUpdateDTO(SQLAlchemyDTO[User]):
    config = SQLAlchemyDTOConfig(exclude={"password_hash"}, partial=True)


class UserService(BaseUserService[User, Any, Any]):  # type: ignore[type-var]
    async def post_registration_hook(self, user: User) -> None:
        print(f"User <{user.email}> has registered!")


s Chemicalalchemy_config = SQLAlchemyAsyncConfig(
    connection_string=DATABASE_URL,
    session_dependency_key="session",
    before_send_handler="autocommit",
)

litestar_users = LitestarUsersPlugin(
    config=LitestarUsersConfig(
        auth_backend_class=SessionAuth,
        secret=ENCODING_SECRET,
        user_model=User,  # pyright: ignore
        user_read_dto=UserReadDTO,
        user_registration_dto=UserRegistrationDTO,
        user_update_dto=UserUpdateDTO,
        user_service_class=UserService,  # pyright: ignore
        auth_handler_config=AuthHandlerConfig(),
        register_handler_config=RegisterHandlerConfig(),
        verification_handler_config=VerificationHandlerConfig(),
    )
)

app = Litestar(
    plugins=[SQLAlchemyInitPlugin(config=sqlalchemy_config), litestar_users],
    route_handlers=[],
)

if __name__ == "__main__":
    uvicorn.run(app="basic:app", reload=True)

```

--------------------------------

### Initiate User Verification

Source: https://mvbosch.github.io/litestar-users/reference/1-user-service

Starts the user verification process for a given user. This is contingent on the `require_verification_on_registration` setting being true during service initialization.

```python
async def initiate_verification(user: SQLAUserT)
```

--------------------------------

### Implement send_verification_token in Python

Source: https://mvbosch.github.io/litestar-users/usage/3-the-user-service

This method is called to send a verification token to a user. It requires the user object and the token string as input. The example shows sending an email using a hypothetical EmailService.

```python
from typing import Any

from litestar_users.service import BaseUserService

from local.models import User
from local.services import EmailService


class UserService(BaseUserService[User, Any, Any]):
    async def send_verification_token(self, user: User, token: str) -> None:
        email_service = EmailService()
        email_service.send(
            email=user.email,
            message=f"Welcome! Your verification link is https://mysite.com/verify?token={token}",
        )

```

--------------------------------

### Extend SQLAlchemy Role Model

Source: https://mvbosch.github.io/litestar-users/usage/1-database-models

Shows how to extend the Role model with custom fields, such as 'created_at'. This example adds a datetime column with a default value of the current time. Customizations are applied directly to the Role model.

```python
from datetime import datetime

from advanced_alchemy.base import UUIDBase
from litestar_users.adapter.sqlalchemy.mixins import SQLAlchemyRoleMixin
from sqlalchemy import DateTime
from sqlalchemy.orm import Mapped, mapped_column


class Role(UUIDBase, SQLAlchemyRoleMixin):
    created_at: Mapped[datetime] = mapped_column(DateTime(), default=datetime.now)


```

--------------------------------

### GET /users/oauth/{oauth}/{account_id}

Source: https://mvbosch.github.io/litestar-users/reference/1-user-service

Retrieve a user by their OAuth account details.

```APIDOC
## GET /users/oauth/{oauth}/{account_id}

### Description
Get a user by OAuth account.

### Method
GET

### Endpoint
/users/oauth/{oauth}/{account_id}

### Parameters
#### Path Parameters
- **oauth** (str) - Required - Name of the OAuth client.
- **account_id** (str) - Required - Id. of the account on the external OAuth service.

#### Query Parameters
- **request** (Request | None) - Optional - The litestar request that initiated the action. Defaults to None.

### Request Example
```json
{
  "oauth": "google",
  "account_id": "109876543210"
}
```

### Response
#### Success Response (200)
- **user_details** (SQLAUserT) - Details of the found user.

#### Response Example
```json
{
  "user_details": {
    "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "email": "user@example.com",
    "username": "testuser"
  }
}
```

### Errors
- **NotFoundError**: The user or OAuth account does not exist.
```

--------------------------------

### GET /roles/name/{name}

Source: https://mvbosch.github.io/litestar-users/reference/1-user-service

Retrieve a role by its name.

```APIDOC
## GET /roles/name/{name}

### Description
Retrieve a role by name.

### Method
GET

### Endpoint
/roles/name/{name}

### Parameters
#### Path Parameters
- **name** (str) - Required - The name of the role.

### Request Example
```json
{
  "name": "editor"
}
```

### Response
#### Success Response (200)
- **id** (UUID | int) - The unique identifier of the role.
- **name** (string) - The name of the role.

#### Response Example
```json
{
  "id": "b2c3d4e5-f6a7-8901-2345-67890abcdef0",
  "name": "editor"
}
```
```

--------------------------------

### GET /roles/{id_}

Source: https://mvbosch.github.io/litestar-users/reference/1-user-service

Retrieve a role by its unique identifier.

```APIDOC
## GET /roles/{id_}

### Description
Retrieve a role by id.

### Method
GET

### Endpoint
/roles/{id_}

### Parameters
#### Path Parameters
- **id_** (UUID | int) - Required - ID of the role.

### Request Example
```json
{
  "id_": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
}
```

### Response
#### Success Response (200)
- **id** (UUID | int) - The unique identifier of the role.
- **name** (string) - The name of the role.

#### Response Example
```json
{
  "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "name": "admin"
}
```
```

--------------------------------

### Get User by OAuth Account

Source: https://mvbosch.github.io/litestar-users/reference/1-user-service

Retrieves a user based on their OAuth account details, including the OAuth client name and the account ID on the external service. It can optionally use the Litestar request object and raises a NotFoundError if the user or account does not exist.

```python
async def get_by_oauth_account(oauth, account_id, request=None):
    """
    Get a user by OAuth account.

    Parameters:
    Name | Type | Description | Default  
    ---|---|---|---
    `oauth` |  `str` |  Name of the OAuth client. |  _required_  
    `account_id` |  `str` |  Id. of the account on the external OAuth service. |  _required_  
    `request` |  `Request | None` |  The litestar request that initiated the action. |  `None`  

    Raises:
    Type | Description  
    ---|---
    `NotFoundError` |  The user or OAuth account does not exist.  

    Returns:
    Type | Description  
    ---|---
    `SQLAUserT` |  A user.  
    """
    pass
```

--------------------------------

### Initialize BaseUserService

Source: https://mvbosch.github.io/litestar-users/reference/1-user-service

Constructs an instance of the BaseUserService. Requires essential parameters like a secret key, user identifier, and user repository. Optional parameters include hash schemes, role/OAuth repositories, and verification requirements.

```python
def __init__(secret: str, user_auth_identifier: str, user_repository: SQLAlchemyUserRepository[SQLAUserT], hash_schemes: Sequence[str] | None = None, role_repository: SQLAlchemyRoleRepository[SQLARoleT, SQLAUserT] | None = None, oauth2_repository: SQLAlchemyOAuthAccountRepository[SQLAOAuthAccountT, SQLAUserT] | None = None, require_verification_on_registration: bool = True)
```

--------------------------------

### Register New User

Source: https://mvbosch.github.io/litestar-users/reference/1-user-service

Handles the registration of a new user using provided data. Optionally accepts a Litestar request object to run custom business logic during registration.

```python
async def register(data: dict[str, Any], request: Request | None = None)
```

--------------------------------

### User Registration API

Source: https://mvbosch.github.io/litestar-users/usage/4-route-handler-configs

Endpoint for registering new users. By default, new users require verification before they can log in.

```APIDOC
## POST /auth/register

### Description
Registers a new user. By default, newly registered users will need to verify their account before they can proceed to login. This behavior can be changed by setting `require_verification_on_registration` to `False`.

### Method
POST

### Endpoint
/auth/register

### Parameters
#### Request Body
- **username** (string) - Required - The desired username for the new user.
- **email** (string) - Required - The email address for the new user.
- **password** (string) - Required - The password for the new user.

### Request Example
```json
{
  "username": "newuser",
  "email": "newuser@example.com",
  "password": "strongPassword123"
}
```

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating successful registration.

#### Response Example
```json
{
  "message": "User registered successfully. Please check your email for verification."
}
```
```

--------------------------------

### POST /oauth2/authorize

Source: https://mvbosch.github.io/litestar-users/reference/1-user-service

Initiate the OAuth2 authorization flow.

```APIDOC
## POST /oauth2/authorize

### Description
Initiate the OAuth2 authorization flow. This endpoint redirects the user to the OAuth provider for authentication and authorization.

### Method
POST

### Endpoint
/oauth2/authorize

### Parameters
#### Request Body
- **request** (Request) - Required - The litestar request object.
- **oauth_client** (str) - Required - The name of the OAuth client (e.g., 'google', 'github').
- **state_secret** (str) - Required - A secret used to generate the state parameter for CSRF protection.
- **callback_route_name** (str) - Required - The name of the route to redirect to after authorization.
- **scopes** (list[str] | None) - Optional - A list of scopes to request from the OAuth provider. Defaults to None.
- **redirect_url** (str | None) - Optional - A specific URL to redirect to after authorization. If not provided, the callback route is used. Defaults to None.
- **state_data** (any | None) - Optional - Additional data to include in the state parameter.

### Request Example
```json
{
  "request": {},
  "oauth_client": "google",
  "state_secret": "your-secret-key",
  "callback_route_name": "oauth_callback",
  "scopes": ["email", "profile"]
}
```

### Response
Redirects the user to the OAuth provider's authorization URL.
```

--------------------------------

### POST /verification/hook

Source: https://mvbosch.github.io/litestar-users/reference/1-user-service

Execute custom business logic after a user has verified their details. Useful for updating sales lead data, etc.

```APIDOC
## POST /verification/hook

### Description
Execute custom logic to run custom business logic after a user has verified details. Useful for eg. updating sales lead data, etc.

### Method
POST

### Endpoint
/verification/hook

### Parameters
#### Request Body
- **user** (SQLAUserT) - Required - User ORM instance.
- **request** (Request | None) - Optional - The litestar request that initiated the action. Defaults to None.

### Notes
Uncaught exceptions in this method could result in returning a HTTP 500 status code while successfully validating the user.

### Request Example
```json
{
  "user": {},
  "request": null
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "Verification hook executed successfully."
}
```
```

--------------------------------

### Authentication Hooks

Source: https://mvbosch.github.io/litestar-users/reference/1-user-service

Customizable hooks for pre- and post-login and registration logic.

```APIDOC
## POST /pre_login_hook

### Description
Execute custom logic to run custom business logic prior to authenticating a user. Useful for authentication checks against external sources, e.g., current membership validity or blacklists, etc. Must return `False` or raise a custom exception to cancel authentication. Uncaught exceptions in this method will break the authentication process.

### Method
POST

### Endpoint
/pre_login_hook

### Parameters
#### Request Body
- **data** (AuthenticationSchema) - Required - Authentication data transfer object.
- **request** (Request | None) - Optional - The litestar request that initiated the action.

### Response
#### Success Response (200)
- **authenticated** (bool) - Indicates if authentication should proceed (true) or be cancelled (false).

#### Response Example
```json
{
  "authenticated": true
}
```

## POST /post_login_hook

### Description
Execute custom logic to run custom business logic after authenticating a user. Useful for, e.g., updating a login counter, updating last known user IP address, etc. Uncaught exceptions in this method will break the authentication process.

### Method
POST

### Endpoint
/post_login_hook

### Parameters
#### Request Body
- **user** (SQLAUserT) - Required - The user who has authenticated.
- **request** (Request | None) - Optional - The litestar request that initiated the action.

### Response
#### Success Response (200)
- **message** (str) - Confirmation message.

#### Response Example
```json
{
  "message": "Post-login logic executed successfully."
}
```

## POST /pre_registration_hook

### Description
Execute custom logic to run custom business logic prior to registering a user. Useful for authorization checks against external sources, e.g., membership API or blacklists, etc. Uncaught exceptions in this method will result in failed registration attempts.

### Method
POST

### Endpoint
/pre_registration_hook

### Parameters
#### Request Body
- **data** (dict[str, Any]) - Required - User creation data transfer object.
- **request** (Request | None) - Optional - The litestar request that initiated the action.

### Response
#### Success Response (200)
- **authorized** (bool) - Indicates if registration should proceed (true) or be cancelled (false).

#### Response Example
```json
{
  "authorized": true
}
```

## POST /post_registration_hook

### Description
Execute custom logic to run custom business logic after registering a user. Useful for updating external datasets, sending welcome messages, etc. Uncaught exceptions in this method could result in returning a HTTP 500 status code while successfully creating the user in the database.

### Method
POST

### Endpoint
/post_registration_hook

### Parameters
#### Request Body
- **user** (SQLAUserT) - Required - User ORM instance.
- **request** (Request | None) - Optional - The litestar request that initiated the action.

### Response
#### Success Response (200)
- **message** (str) - Confirmation message.

#### Response Example
```json
{
  "message": "Post-registration logic executed successfully."
}
```
```

--------------------------------

### Add User to Service

Source: https://mvbosch.github.io/litestar-users/reference/1-user-service

Programmatically creates a new user within the service. Allows specifying whether the user should be verified and activated upon creation. Defaults to activating the user but not verifying.

```python
async def add_user(user: SQLAUserT, verify: bool = False, activate: bool = True)
```

--------------------------------

### POST /oauth2/callback

Source: https://mvbosch.github.io/litestar-users/reference/1-user-service

Handle the callback after a successful OAuth authentication.

```APIDOC
## POST /oauth2/callback

### Description
Handle the callback after a successful OAuth authentication. This endpoint receives the authorization code or token from the OAuth provider and completes the login or account association process.

### Method
POST

### Endpoint
/oauth2/callback

### Parameters
#### Request Body
- **data** (dict) - Required - Data received from the OAuth provider, typically including authorization code or token.
- **oauth_client** (str) - Required - The name of the OAuth client.
- **state_secret** (str) - Required - The secret used to verify the state parameter.
- **callback_route_name** (str) - Required - The name of the route to redirect to.
- **request** (Request) - Required - The litestar request object.
- **redirect_url** (str | None) - Optional - A specific URL to redirect to after processing the callback. Defaults to None.
- **associate_by_email** (bool) - Optional - If True, any existing user with the same e-mail address will be associated to this user. Defaults to False.
- **is_verified_by_default** (bool) - Optional - If True, the `is_verified` flag will be set to `True` on newly created user. Make sure the OAuth Provider you're using does verify the email address before enabling this flag. Defaults to False.
- **is_associate_callback** (bool) - Optional - If True, the callback is an associate callback. Defaults to False.
- **associate_user** (SQLAUserT | None) - Optional - The user to associate the OAuth account to, if applicable. Defaults to None.

### Request Example
```json
{
  "data": {
    "code": "authorization_code_from_provider"
  },
  "oauth_client": "google",
  "state_secret": "your-secret-key",
  "callback_route_name": "oauth_callback",
  "request": {},
  "associate_by_email": true
}
```

### Response
#### Success Response (200)
- **user** (SQLAUserT) - The authenticated or newly created user object.

#### Response Example
```json
{
  "user": {
    "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "email": "user@example.com",
    "username": "authenticated_user"
  }
}
```

### Notes
- If the user already exists with this OAuth account, the token is updated.
- If a user with the same email already exists and `associate_by_email` is True, the OAuth account is associated to this user.
- Otherwise, the `UserNotExists` exception is raised.
- If the user does not exist, it is created and the `on_after_register` handler is triggered.
```

--------------------------------

### OAuth2 Authorization and Callback Handling

Source: https://mvbosch.github.io/litestar-users/reference/1-user-service

Functions for managing the OAuth2 authorization flow. `oauth2_authorize` initiates the authorization process, while `oauth2_callback` handles the response from the OAuth provider. The callback function manages user creation, association by email, and verification status.

```python
async def oauth2_authorize(request, oauth_client, state_secret, callback_route_name, scopes=None, redirect_url=None, state_data=None):
    """
    Initiates the OAuth2 authorization flow.
    """
    pass

async def oauth2_callback(data, oauth_client, state_secret, callback_route_name, request, redirect_url=None, associate_by_email=False, is_verified_by_default=False, is_associate_callback=False, associate_user=None):
    """
    Handle the callback after a successful OAuth authentication.
    If the user already exists with this OAuth account, the token is updated.
    If a user with the same e-mail already exists and `associate_by_email` is True, the OAuth account is associated to this user. Otherwise, the `UserNotExists` exception is raised.
    If the user does not exist, it is created and the on_after_register handler is triggered.
    :param oauth_name: Name of the OAuth client. :param access_token: Valid access token for the service provider. :param account_id: models.ID of the user on the service provider. :param account_email: E-mail of the user on the service provider. :param expires_at: Optional timestamp at which the access token expires. :param refresh_token: Optional refresh token to get a fresh access token from the service provider. :param request: Optional FastAPI request that triggered the operation, defaults to None :param associate_by_email: If True, any existing user with the same e-mail address will be associated to this user. Defaults to False. :param is_verified_by_default: If True, the `is_verified` flag will be set to `True` on newly created user. Make sure the OAuth Provider you're using does verify the email address before enabling this flag. Defaults to False. :param is_associate_callback: If True, the callback is an associate callback. :param associate_user: The user to associate the OAuth account to. :return: A user.
    """
    pass
```

--------------------------------

### POST /roles

Source: https://mvbosch.github.io/litestar-users/reference/1-user-service

Add a new role to the database.

```APIDOC
## POST /roles

### Description
Add a new role to the database.

### Method
POST

### Endpoint
/roles

### Parameters
#### Request Body
- **data** (SQLARoleT) - Required - A role creation data transfer object.

### Request Example
```json
{
  "data": {
    "name": "viewer"
  }
}
```

### Response
#### Success Response (200)
- **id** (UUID | int) - The unique identifier of the newly created role.
- **name** (string) - The name of the newly created role.

#### Response Example
```json
{
  "id": "c3d4e5f6-a7b8-9012-3456-7890abcdef01",
  "name": "viewer"
}
```
```

--------------------------------

### Retrieve User by Attributes

Source: https://mvbosch.github.io/litestar-users/reference/1-user-service

Finds a user based on arbitrary keyword arguments provided as filters. Allows for flexible querying and optional loading of relationships and execution options.

```python
async def get_user_by(load: LoadSpec | None = None, execution_options: dict[str, Any] | None = None, **kwargs: Any)
```

--------------------------------

### User Verification and Token Management

Source: https://mvbosch.github.io/litestar-users/reference/1-user-service

Endpoints related to user verification and token management.

```APIDOC
## POST /send_verification_token

### Description
Execute custom logic to send the verification token to the relevant user. Developers need to override this method to facilitate sending the token via email, SMS, etc. This method is not invoked when `require_verification_on_registration` is set to `False`.

### Method
POST

### Endpoint
/send_verification_token

### Parameters
#### Request Body
- **user** (SQLAUserT) - Required - The user requesting verification.
- **token** (str) - Required - An encoded JWT bound to verification.

### Response
#### Success Response (200)
- **message** (str) - Confirmation message.

#### Response Example
```json
{
  "message": "Verification token sent successfully."
}
```

## POST /verify

### Description
Verify a user with the given JWT. This endpoint can optionally take the `request` object for context.

### Method
POST

### Endpoint
/verify

### Parameters
#### Request Body
- **encoded_token** (str) - Required - An encoded JWT bound to verification.
- **request** (Request | None) - Optional - The litestar request that initiated the action.

### Response
#### Success Response (200)
- **message** (str) - Confirmation message indicating successful verification.

#### Response Example
```json
{
  "message": "User verified successfully."
}
```

### Error Handling
- **InvalidTokenException**: If the token is expired or tampered with.
```

--------------------------------

### Authenticate User

Source: https://mvbosch.github.io/litestar-users/reference/1-user-service

Verifies user credentials using provided data. Can optionally integrate with the Litestar request object for further processing.

```python
async def authenticate(data: Any, request: Request | None = None)
```

--------------------------------

### Default Route Handler Tags Configuration

Source: https://mvbosch.github.io/litestar-users/reference/2-route-handler-configs

Demonstrates the default configuration for route handler tags, which is typically `None`. These tags can be used to group and organize routes in API documentation.

```python
tags = None
```

--------------------------------

### Verification API

Source: https://mvbosch.github.io/litestar-users/usage/4-route-handler-configs

Endpoint for verifying a user's account using a token.

```APIDOC
## POST /auth/verify

### Description
Updates a user's `is_verified` status to `True`, given a valid token. This is typically used after a user signs up and clicks a verification link sent to their email.

### Method
POST

### Endpoint
/auth/verify

### Parameters
#### Request Body
- **token** (string) - Required - The verification token sent to the user's email.

### Request Example
```json
{
  "token": "valid_verification_token"
}
```

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating successful verification.

#### Response Example
```json
{
  "message": "Account verified successfully."
}
```
```

--------------------------------

### Post-Verification Hook for User Details

Source: https://mvbosch.github.io/litestar-users/reference/1-user-service

Executes custom business logic after a user has verified their details. This is useful for tasks like updating sales lead data. It accepts a user ORM instance and an optional Litestar request. Uncaught exceptions can lead to a 500 status code.

```python
async def post_verification_hook(user, request=None):
    """
    Execute custom logic to run custom business logic after a user has verified details.
    Useful for eg. updating sales lead data, etc.

    Parameters:
    Name | Type | Description | Default  
    ---|---|---|---
    `user` |  `SQLAUserT` |  User ORM instance. |  _required_  
    `request` |  `Request | None` |  The litestar request that initiated the action. |  `None`  

    Notes: - Uncaught exceptions in this method could result in returning a HTTP 500 status code while successfully validating the user.
    """
    pass
```

--------------------------------

### Retrieve User by ID

Source: https://mvbosch.github.io/litestar-users/reference/1-user-service

Fetches a user from the database using their unique ID. Supports optional loading of related entities and execution options for query customization.

```python
async def get_user(id_: UUID | int, load: LoadSpec | None = None, execution_options: dict[str, Any] | None = None)
```

--------------------------------

### Define SQLAlchemy OAuthAccount and User Models

Source: https://mvbosch.github.io/litestar-users/usage/1-database-models

Sets up OAuthAccount and User models for OAuth2 integration. Includes the OAuthAccount model inheriting from SQLAlchemyOAuthAccountMixin and establishes a relationship in the User model. Requires manual definition of 'User.oauth_accounts' and association.

```python
from uuid import UUID
from advanced_alchemy.base import UUIDBase
from litestar_users.adapter.sqlalchemy.mixins import (
    SQLAlchemyOAuthAccountMixin,
    SQLAlchemyUserMixin,
)
from sqlalchemy import ForeignKey, Uuid
from sqlalchemy.orm import Mapped, mapped_column, relationship


class OAuthAccount(UUIDBase, SQLAlchemyOAuthAccountMixin):
    """OAuth account model."""

    user_id: Mapped[UUID] = mapped_column(Uuid(), ForeignKey("user.id"))


class User(UUIDBase, SQLAlchemyUserMixin):
    """User model."""

    oauth_accounts: Mapped[list[OAuthAccount]] = relationship(
        OAuthAccount, lazy="selectin"
    )


```

--------------------------------

### Schema Tags Configuration for Route Handlers

Source: https://mvbosch.github.io/litestar-users/reference/2-route-handler-configs

Allows appending a list of string tags to the schema of route handlers. This is useful for organizing and filtering API documentation. It defaults to None.

```python
tags = None

```

--------------------------------

### Role Management API

Source: https://mvbosch.github.io/litestar-users/usage/4-route-handler-configs

Endpoints for managing roles, including creating, updating, deleting, assigning, and revoking roles for users.

```APIDOC
## POST /roles

### Description
Creates a new role.

### Method
POST

### Endpoint
/roles

### Parameters
#### Request Body
- **name** (string) - Required - The name of the role to create.

### Request Example
```json
{
  "name": "editor"
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the newly created role.
- **name** (string) - The name of the created role.

#### Response Example
```json
{
  "id": "role-abc",
  "name": "editor"
}
```

## PUT /roles/{role_id}

### Description
Updates an existing role.

### Method
PUT

### Endpoint
/roles/{role_id}

### Parameters
#### Path Parameters
- **role_id** (string) - Required - The ID of the role to update.
#### Request Body
- **name** (string) - Required - The new name for the role.

### Request Example
```json
{
  "name": "content_manager"
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the updated role.
- **name** (string) - The new name of the role.

#### Response Example
```json
{
  "id": "role-abc",
  "name": "content_manager"
}
```

## DELETE /roles/{role_id}

### Description
Deletes a role from the database.

### Method
DELETE

### Endpoint
/roles/{role_id}

### Parameters
#### Path Parameters
- **role_id** (string) - Required - The ID of the role to delete.

### Request Example
```json
{} // No request body
```

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating the role was deleted.

#### Response Example
```json
{
  "message": "Role deleted successfully."
}
```

## POST /users/{user_id}/roles

### Description
Assigns an existing role to an existing user.

### Method
POST

### Endpoint
/users/{user_id}/roles

### Parameters
#### Path Parameters
- **user_id** (string) - Required - The ID of the user to assign the role to.
#### Request Body
- **role_id** (string) - Required - The ID of the role to assign.

### Request Example
```json
{
  "role_id": "role-abc"
}
```

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating the role was assigned.

#### Response Example
```json
{
  "message": "Role assigned successfully to user."
}
```

## DELETE /users/{user_id}/roles/{role_id}

### Description
Revokes an existing role from an existing user.

### Method
DELETE

### Endpoint
/users/{user_id}/roles/{role_id}

### Parameters
#### Path Parameters
- **user_id** (string) - Required - The ID of the user to revoke the role from.
- **role_id** (string) - Required - The ID of the role to revoke.

### Request Example
```json
{} // No request body
```

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating the role was revoked.

#### Response Example
```json
{
  "message": "Role revoked successfully from user."
}
```
```

--------------------------------

### LitestarUsersConfig: Registration Handler Configuration

Source: https://mvbosch.github.io/litestar-users/reference/0-config

Optional configuration for the user registration (signup) route handler. If provided, this enables and configures the routes for user registration.

```python
register_handler_config = None
```

--------------------------------

### User Management API

Source: https://mvbosch.github.io/litestar-users/usage/4-route-handler-configs

Endpoints for managing users, including retrieving, updating, and deleting user accounts.

```APIDOC
## GET /users/{user_id}

### Description
Retrieves information about a specific user.

### Method
GET

### Endpoint
/users/{user_id}

### Parameters
#### Path Parameters
- **user_id** (string) - Required - The ID of the user to retrieve.

### Request Example
```json
{} // No request body
```

### Response
#### Success Response (200)
- **id** (string) - The user's unique identifier.
- **username** (string) - The user's username.
- **email** (string) - The user's email address.

#### Response Example
```json
{
  "id": "user-123",
  "username": "testuser",
  "email": "test@example.com"
}
```

## PUT /users/{user_id}

### Description
Updates the information of a specific user.

### Method
PUT

### Endpoint
/users/{user_id}

### Parameters
#### Path Parameters
- **user_id** (string) - Required - The ID of the user to update.
#### Request Body
- **email** (string) - Optional - The new email address for the user.
- **username** (string) - Optional - The new username for the user.

### Request Example
```json
{
  "email": "updated.user@example.com"
}
```

### Response
#### Success Response (200)
- **id** (string) - The user's unique identifier.
- **username** (string) - The updated username.
- **email** (string) - The updated email address.

#### Response Example
```json
{
  "id": "user-123",
  "username": "testuser",
  "email": "updated.user@example.com"
}
```

## DELETE /users/{user_id}

### Description
Deletes a user from the database.

### Method
DELETE

### Endpoint
/users/{user_id}

### Parameters
#### Path Parameters
- **user_id** (string) - Required - The ID of the user to delete.

### Request Example
```json
{} // No request body
```

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating the user was deleted.

#### Response Example
```json
{
  "message": "User deleted successfully."
}
```
```

--------------------------------

### Define SQLAlchemy Role and User Models for RBAC

Source: https://mvbosch.github.io/litestar-users/usage/1-database-models

Sets up Role and User models for Role-Based Access Control (RBAC) using SQLAlchemy. Includes a UserRole association table. Requires manual definition of the 'User.roles' relationship and association table.

```python
from uuid import UUID
from advanced_alchemy.base import UUIDBase
from litestar_users.adapter.sqlalchemy.mixins import (
    SQLAlchemyUserMixin,
    SQLAlchemyRoleMixin,
)
from sqlalchemy import ForeignKey, Uuid
from sqlalchemy.orm import Mapped, mapped_column, relationship


class Role(UUIDBase, SQLAlchemyRoleMixin):
    """Role model."""


class User(UUIDBase, SQLAlchemyUserMixin):
    """User model."""

    roles: Mapped[list[Role]] = relationship(
        "Role", secondary="user_role", lazy="selectin"
    )


class UserRole(UUIDBase):
    """User role association model."""

    user_id: Mapped[UUID] = mapped_column(Uuid(), ForeignKey("user.id"))
    role_id: Mapped[UUID] = mapped_column(Uuid(), ForeignKey("role.id"))


```

--------------------------------

### LitestarUsersConfig: Role Create DTO

Source: https://mvbosch.github.io/litestar-users/reference/0-config

Defines the SQLAlchemyDTO based on the Role ORM model for creating roles. This is required when `role_management_handler_config` is set.

```python
role_create_dto = None
```

--------------------------------

### POST /users/{user_id}/roles/{role_id}

Source: https://mvbosch.github.io/litestar-users/reference/1-user-service

Assign a role to a specific user.

```APIDOC
## POST /users/{user_id}/roles/{role_id}

### Description
Add a role to a user.

### Method
POST

### Endpoint
/users/{user_id}/roles/{role_id}

### Parameters
#### Path Parameters
- **user_id** (UUID | int) - Required - ID of the user to receive the role.
- **role_id** (UUID | int) - Required - ID of the role to add to the user.

### Request Example
```json
{
  "user_id": "f6a7b8c9-d0e1-2345-6789-0abcdef01234",
  "role_id": "01234567-89ab-cdef-0123-456789abcdef"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the role was assigned.

#### Response Example
```json
{
  "message": "Role with ID 01234567-89ab-cdef-0123-456789abcdef assigned to user ID f6a7b8c9-d0e1-2345-6789-0abcdef01234."
}
```
```

--------------------------------

### Default Guards Configuration

Source: https://mvbosch.github.io/litestar-users/reference/2-route-handler-configs

Illustrates the default configuration for guards, which is an empty list using `field(default_factory=list)`. Guards are used to enforce authorization policies on route handlers.

```python
from dataclasses import field

guards = field(default_factory=list)
```

--------------------------------

### OAuth2 Integration API

Source: https://mvbosch.github.io/litestar-users/usage/4-route-handler-configs

Endpoints for handling OAuth2 authorization flows, including initiating the authorization process and handling provider callbacks.

```APIDOC
## GET /auth/oauth2/authorize

### Description
Redirects the user to the OAuth2 provider's authorization page to initiate the login/authorization process.

### Method
GET

### Endpoint
/auth/oauth2/authorize

### Parameters
#### Query Parameters
- **provider** (string) - Required - The name of the OAuth2 provider (e.g., 'google', 'github').

### Request Example
```json
{} // No request body, query parameter is used
```

### Response
#### Success Response (302 Redirect)
- **Location** (header) - The URL of the OAuth2 provider's authorization page.

## POST /auth/oauth2/callback

### Description
Handles the callback from the OAuth2 provider after the user has authorized the application.

### Method
POST

### Endpoint
/auth/oauth2/callback

### Parameters
#### Request Body
- **provider** (string) - Required - The name of the OAuth2 provider.
- **code** (string) - Required - The authorization code received from the provider.
- **state** (string) - Optional - The state parameter used for CSRF protection.

### Request Example
```json
{
  "provider": "google",
  "code": "authorization_code_from_google",
  "state": "random_state_string"
}
```

### Response
#### Success Response (200)
- **access_token** (string) - The authentication token obtained after successful OAuth2 flow.
- **refresh_token** (string) - The refresh token.

#### Response Example
```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "abc123xyz789..."
}
```
```

--------------------------------

### Default User Verification Status Configuration

Source: https://mvbosch.github.io/litestar-users/reference/2-route-handler-configs

A boolean flag to set the default verification status for newly created users. Defaults to False, meaning users are not verified by default. This impacts user account activation.

```python
is_verified_by_default = False

```

--------------------------------

### LitestarUsersConfig: Session Backend Configuration

Source: https://mvbosch.github.io/litestar-users/reference/0-config

Optional configuration for the session backend. This is required if the `auth_backend_class` is set to `SessionAuth` and enables session-based authentication.

```python
session_backend_config = None
```

--------------------------------

### Generate JWT Token

Source: https://mvbosch.github.io/litestar-users/reference/1-user-service

Creates a time-limited JSON Web Token (JWT) for a given user ID and audience. This token can be used for authentication and authorization.

```python
def generate_token(user_id: UUID | int, aud: str)
```

--------------------------------

### Password Reset Management

Source: https://mvbosch.github.io/litestar-users/reference/1-user-service

Endpoints for initiating and performing password resets.

```APIDOC
## POST /initiate_password_reset

### Description
Initiate the password reset flow for a user.

### Method
POST

### Endpoint
/initiate_password_reset

### Parameters
#### Request Body
- **email** (str) - Required - Email of the user who has forgotten their password.

### Response
#### Success Response (200)
- **message** (str) - Confirmation message that the password reset process has been initiated.

#### Response Example
```json
{
  "message": "Password reset initiated. Please check your email."
}
```

## POST /send_password_reset_token

### Description
Execute custom logic to send the password reset token to the relevant user. Developers need to override this method to facilitate sending the token via email, SMS, etc.

### Method
POST

### Endpoint
/send_password_reset_token

### Parameters
#### Request Body
- **user** (SQLAUserT) - Required - The user requesting the password reset.
- **token** (str) - Required - An encoded JWT bound to the password reset flow.

### Response
#### Success Response (200)
- **message** (str) - Confirmation message that the password reset token has been sent.

#### Response Example
```json
{
  "message": "Password reset token sent successfully."
}
```

## POST /reset_password

### Description
Reset a user's password given a valid JWT.

### Method
POST

### Endpoint
/reset_password

### Parameters
#### Request Body
- **encoded_token** (str) - Required - An encoded JWT bound to the password reset flow.
- **password** (str) - Required - The new password to hash and store.

### Response
#### Success Response (200)
- **message** (str) - Confirmation message indicating successful password reset.

#### Response Example
```json
{
  "message": "Password reset successfully."
}
```

### Error Handling
- **InvalidTokenException**: If the token has expired or been tampered with.
```

--------------------------------

### User Association by Email Configuration

Source: https://mvbosch.github.io/litestar-users/reference/2-route-handler-configs

A boolean flag to determine if existing users should be associated by their email address. Defaults to False, preventing automatic association. This controls user linking logic.

```python
associate_by_email = False

```

--------------------------------

### Role Management Functions

Source: https://mvbosch.github.io/litestar-users/reference/1-user-service

Provides asynchronous functions for managing roles, including retrieving roles by ID or name, adding new roles, updating existing roles, and deleting roles. These functions operate on role data transfer objects and identifiers.

```python
async def get_role(id_):
    """
    Retrieve a role by id.

    Parameters:
    Name | Type | Description | Default  
    ---|---|---|---
    `id_` |  `UUID | int` |  ID of the role. |  _required_  
    """
    pass

async def get_role_by_name(name):
    """
    Retrieve a role by name.

    Parameters:
    Name | Type | Description | Default  
    ---|---|---|---
    `name` |  `str` |  The name of the role. |  _required_  
    """
    pass

async def add_role(data):
    """
    Add a new role to the database.

    Parameters:
    Name | Type | Description | Default  
    ---|---|---|---
    `data` |  `SQLARoleT` |  A role creation data transfer object. |  _required_  
    """
    pass

async def update_role(id_, data):
    """
    Update a role in the database.

    Parameters:
    Name | Type | Description | Default  
    ---|---|---|---
    `id_` |  `UUID | int` |  UUID corresponding to the role primary key. |  _required_  
    `data` |  `SQLARoleT` |  A role update data transfer object. |  _required_  
    """
    pass

async def delete_role(id_):
    """
    Delete a role from the database.

    Parameters:
    Name | Type | Description | Default  
    ---|---|---|---
    `id_` |  `UUID | int` |  UUID corresponding to the role primary key. |  _required_  
    """
    pass
```

--------------------------------

### OAuth2 Client Configuration in Litestar

Source: https://mvbosch.github.io/litestar-users/reference/2-route-handler-configs

Defines the OAuth2 client instance attribute used for authentication flows. No specific dependencies are mentioned, and it accepts an OAuth2 client object as input.

```python
oauth_client

```

--------------------------------

### Password Reset API

Source: https://mvbosch.github.io/litestar-users/usage/4-route-handler-configs

Endpoints for initiating and completing the password reset process.

```APIDOC
## POST /auth/forgot-password

### Description
Initiates the password reset flow for a user.

### Method
POST

### Endpoint
/auth/forgot-password

### Parameters
#### Request Body
- **email** (string) - Required - The email address associated with the user's account.

### Request Example
```json
{
  "email": "user@example.com"
}
```

### Response
#### Success Response (200)
- **message** (string) - A confirmation message that the password reset process has been initiated.

#### Response Example
```json
{
  "message": "Password reset email sent."
}
```

## POST /auth/reset-password

### Description
Resets a user's password using a valid reset token.

### Method
POST

### Endpoint
/auth/reset-password

### Parameters
#### Request Body
- **reset_token** (string) - Required - The token received via email to reset the password.
- **new_password** (string) - Required - The new password for the user.

### Request Example
```json
{
  "reset_token": "valid_reset_token_from_email",
  "new_password": "newSecurePassword123"
}
```

### Response
#### Success Response (200)
- **message** (string) - A confirmation message that the password has been successfully reset.

#### Response Example
```json
{
  "message": "Password successfully reset."
}
```
```

--------------------------------

### Define Basic SQLAlchemy User Model

Source: https://mvbosch.github.io/litestar-users/usage/1-database-models

Defines a basic User model using SQLAlchemy and Litestar-Users. It inherits from UUIDBase and SQLAlchemyUserMixin, providing essential columns like email and password hash. Requires SQLAlchemyPlugin for session management.

```python
from advanced_alchemy.base import UUIDBase
from litestar_users.adapter.sqlalchemy.mixins import SQLAlchemyUserMixin


class User(UUIDBase, SQLAlchemyUserMixin):
    """User model."""


```

--------------------------------

### Configure User Management Handler Paths

Source: https://mvbosch.github.io/litestar-users/reference/2-route-handler-configs

Defines the path prefix for user management routes (read, update, delete). These routes typically require administrative privileges and are configured via UserManagementHandlerConfig.

```python
path_prefix = '/users'
```
Tokens:
Raw