User Service

litestar_users.service.BaseUserService

Bases: Generic[SQLAUserT, SQLARoleT]

Main user management interface.

init

__init__(secret, user_auth_identifier, user_repository, hash_schemes=None, role_repository=None, require_verification_on_registration=True)

User service constructor.

Parameters:

Name	Type	Description	Default
`secret`	`str`	Secret string for securely signing tokens.	required
`user_auth_identifier`	`str`	The `User` model attribute to identify the user during authorization.	required
`user_repository`	`SQLAlchemyUserRepository[SQLAUserT]`	A `UserRepository` instance.	required
`hash_schemes`	`Sequence[str] \| None`	Schemes to use for password encryption.	`None`
`role_repository`	`SQLAlchemyRoleRepository[SQLARoleT, SQLAUserT] \| None`	A `RoleRepository` instance.	`None`
`require_verification_on_registration`	`bool`	Whether the registration of a new user requires verification.	`True`

add_user `async`

add_user(user, verify=False, activate=True)

Create a new user programmatically.

Parameters:

Name	Type	Description	Default
`user`	`SQLAUserT`	User model instance.	required
`verify`	`bool`	Set the user's verification status to this value.	`False`
`activate`	`bool`	Set the user's active status to this value.	`True`

register `async`

register(data, request=None)

Register a new user and optionally run custom business logic.

Parameters:

Name	Type	Description	Default
`data`	`dict[str, Any]`	User creation data transfer object.	required
`request`	`Request \| None`	The litestar request that initiated the action.	`None`

get_user `async`

get_user(id_)

Retrieve a user from the database by id.

Parameters:

Name	Type	Description	Default
`id_`	`UUID \| int`	UUID corresponding to a user primary key.	required

get_user_by `async`

get_user_by(**kwargs)

Retrieve a user from the database by arbitrary keyword arguments.

Parameters:

Name	Type	Description	Default
`**kwargs`	`Any`	Keyword arguments to pass as filters.	`{}`

Examples:

service = UserService(...)
john = await service.get_one(email="john@example.com")

update_user `async`

update_user(data)

Update arbitrary user attributes in the database.

Parameters:

Name	Type	Description	Default
`data`	`SQLAUserT`	User update data transfer object.	required

delete_user `async`

delete_user(id_)

Delete a user from the database.

Parameters:

Name	Type	Description	Default
`id_`	`UUID \| int`	UUID corresponding to a user primary key.	required

authenticate `async`

authenticate(data, request=None)

Authenticate a user.

Parameters:

Name	Type	Description	Default
`data`	`Any`	User authentication data transfer object.	required
`request`	`Request \| None`	The litestar request that initiated the action.	`None`

generate_token

generate_token(user_id, aud)

Generate a limited time valid JWT.

Parameters:

Name	Type	Description	Default
`user_id`	`UUID \| int`	ID of the user to provide the token to.	required
`aud`	`str`	Context of the token	required

initiate_verification `async`

initiate_verification(user)

Initiate the user verification flow.

Parameters:

Name	Type	Description	Default
`user`	`SQLAUserT`	The user requesting verification.	required

Notes

The user verification flow is not initiated when require_verification_on_registration is set to False.

send_verification_token `async`

send_verification_token(user, token)

Execute custom logic to send the verification token to the relevant user.

Parameters:

Name	Type	Description	Default
`user`	`SQLAUserT`	The user requesting verification.	required
`token`	`str`	An encoded JWT bound to verification.	required

Notes: - Develepors 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.

verify `async`

verify(encoded_token, request=None)

Verify a user with the given JWT.

Parameters:

Name	Type	Description	Default
`encoded_token`	`str`	An encoded JWT bound to verification.	required
`request`	`Request \| None`	The litestar request that initiated the action.	`None`

Raises:

Type	Description
`InvalidTokenException`	If the token is expired or tampered with.

initiate_password_reset `async`

initiate_password_reset(email)

Initiate the password reset flow.

Parameters:

Name	Type	Description	Default
`email`	`str`	Email of the user who has forgotten their password.	required

send_password_reset_token `async`

send_password_reset_token(user, token)

Execute custom logic to send the password reset token to the relevant user.

Parameters:

Name	Type	Description	Default
`user`	`SQLAUserT`	The user requesting the password reset.	required
`token`	`str`	An encoded JWT bound to the password reset flow.	required

Notes: - Develepors need to override this method to facilitate sending the token via email, sms etc.

reset_password `async`

reset_password(encoded_token, password)

Reset a user's password given a valid JWT.

Parameters:

Name	Type	Description	Default
`encoded_token`	`str`	An encoded JWT bound to the password reset flow.	required
`password`	`str`	The new password to hash and store.	required

Raises:

Type	Description
`InvalidTokenException`	If the token has expired or been tampered with.

pre_login_hook `async`

pre_login_hook(data, request=None)

Execute custom logic to run custom business logic prior to authenticating a user.

Useful for authentication checks against external sources, eg. current membership validity or blacklists, etc Must return False or raise a custom exception to cancel authentication.

Parameters:

Name	Type	Description	Default
`data`	`AuthenticationSchema`	Authentication data transfer object.	required
`request`	`Request \| None`	The litestar request that initiated the action.	`None`

Notes

Uncaught exceptions in this method will break the authentication process.

post_login_hook `async`

post_login_hook(user, request=None)

Execute custom logic to run custom business logic after authenticating a user.

Useful for eg. updating a login counter, updating last known user IP address, etc.

Parameters:

Name	Type	Description	Default
`user`	`SQLAUserT`	The user who has authenticated.	required
`request`	`Request \| None`	The litestar request that initiated the action.	`None`

Notes

Uncaught exceptions in this method will break the authentication process.

pre_registration_hook `async`

pre_registration_hook(data, request=None)

Execute custom logic to run custom business logic prior to registering a user.

Useful for authorization checks against external sources, eg. membership API or blacklists, etc.

Parameters:

Name	Type	Description	Default
`data`	`dict[str, Any]`	User creation data transfer object	required
`request`	`Request \| None`	The litestar request that initiated the action.	`None`

Notes: - Uncaught exceptions in this method will result in failed registration attempts.

post_registration_hook `async`

post_registration_hook(user, request=None)

Execute custom logic to run custom business logic after registering a user.

Useful for updating external datasets, sending welcome messages 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 creating the user in the database.

post_verification_hook `async`

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.

get_role `async`

get_role(id_)

Retrieve a role by id.

Parameters:

Name	Type	Description	Default
`id_`	`UUID \| int`	ID of the role.	required

get_role_by_name `async`

get_role_by_name(name)

Retrieve a role by name.

Parameters:

Name	Type	Description	Default
`name`	`str`	The name of the role.	required

add_role `async`

add_role(data)

Add a new role to the database.

Parameters:

Name	Type	Description	Default
`data`	`SQLARoleT`	A role creation data transfer object.	required

update_role `async`

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

delete_role `async`

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

assign_role `async`

assign_role(user_id, role_id)

Add a role to a user.

Parameters:

Name	Type	Description	Default
`user_id`	`UUID \| int`	ID of the user to receive the role.	required
`role_id`	`UUID \| int`	ID of the role to add to the user.	required

revoke_role `async`

revoke_role(user_id, role_id)

Revoke a role from a user.

Parameters:

Name	Type	Description	Default
`user_id`	`UUID \| int`	ID of the user to revoke the role from.	required
`role_id`	`UUID \| int`	ID of the role to revoke.	required

User Service

litestar_users.service.BaseUserService

__init__

add_user async

register async

get_user async

get_user_by async

update_user async

delete_user async

authenticate async

generate_token

initiate_verification async

send_verification_token async

verify async

initiate_password_reset async

send_password_reset_token async

reset_password async

pre_login_hook async

post_login_hook async

pre_registration_hook async

post_registration_hook async

post_verification_hook async

get_role async

get_role_by_name async

add_role async

update_role async

delete_role async

assign_role async

revoke_role async

init

add_user `async`

register `async`

get_user `async`

get_user_by `async`

update_user `async`

delete_user `async`

authenticate `async`

initiate_verification `async`

send_verification_token `async`

verify `async`

initiate_password_reset `async`

send_password_reset_token `async`

reset_password `async`

pre_login_hook `async`

post_login_hook `async`

pre_registration_hook `async`

post_registration_hook `async`

post_verification_hook `async`

get_role `async`

get_role_by_name `async`

add_role `async`

update_role `async`

delete_role `async`

assign_role `async`

revoke_role `async`