auth

Authentication endpoint handlers.

AuthEndpoint

Bases: BaseEndpoint

Handles authentication-related API endpoints.

Provides methods for login, registration, token refresh, and user management.

login(credentials) async

Authenticate with email and password.

Parameters:

Name	Type	Description	Default
credentials	UserAuthentication	User authentication credentials (email and password)	required

Returns:

Type	Description
TokenPair	Token information including access_token and refresh_token

Raises:

Type	Description
AuthenticationError	If credentials are invalid

Example

from yousleep_common.models import UserAuthentication

credentials = UserAuthentication(
    email="user@example.com",
    password="secure_password"
)
tokens = await client.auth.login(credentials)

refresh(refresh_token) async

Refresh access token using refresh token.

The server reads the refresh token only from the bearer header, so this request sends it there in place of the client's own credential.

Parameters:

Name	Type	Description	Default
refresh_token	str	Valid refresh token	required

Returns:

Type	Description
AccessToken	New access token information

Raises:

Type	Description
AuthenticationError	If refresh token is invalid or expired

register(registration) async

Register a new user account.

Parameters:

Name	Type	Description	Default
registration	UserRegistration	User registration information	required

Returns:

Type	Description
UserOut	Created user information

Raises:

Type	Description
ValidationError	If registration data is invalid

Example

from yousleep_common.models import UserRegistration
from yousleep_common.types import UsageType

registration = UserRegistration(
    email="user@example.com",
    password="secure_password",
    name="Jane Ríos",
    organization="My Lab",  # or "Independent"
    usage_type=UsageType.RESEARCH,
    purpose="Sleep-staging research on our EEG cohort",
    position="Researcher",  # optional
)
user = await client.auth.register(registration)

request_password_reset(request) async

Request a password reset email.

The answer is the same whether or not an account with the address exists. No authentication is needed.

Parameters:

Name	Type	Description	Default
request	PasswordResetEmailRequest	The address of the account	required

Returns:

Type	Description
MessageResponse	Message confirming the request

Example

from yousleep_common.models import PasswordResetEmailRequest

response = await client.auth.request_password_reset(
    PasswordResetEmailRequest(email="user@example.com")
)
print(response.message)

resend_confirmation_email(request) async

Resend the email confirmation link to an address.

The answer is the same whether or not an account with that address exists, or is already confirmed, so the call cannot be used to probe for accounts. No authentication is needed.

Parameters:

Name	Type	Description	Default
request	VerificationEmailRequest	The address of the account to confirm	required

Returns:

Type	Description
MessageResponse	Message saying a link was sent if the account exists

Example

from yousleep_common.models import VerificationEmailRequest

response = await client.auth.resend_confirmation_email(
    VerificationEmailRequest(email="user@example.com")
)
print(response.message)

reset_password(token, request) async

Set a new password with the token from a reset or setup link.

Parameters:

Name	Type	Description	Default
token	str	Password reset token from the email	required
request	ResetPasswordRequest	The new password. The server's password policy decides whether it is accepted.	required

Returns:

Type	Description
MessageResponse	Message confirming the password change

Raises:

Type	Description
NotFoundError	If the token is invalid, expired or already used
YouSleepClientError	With status 400 if the password does not meet the policy, or the account is disabled or unconfirmed

Example

from yousleep_common.models import ResetPasswordRequest

response = await client.auth.reset_password(
    "reset-token-from-email",
    ResetPasswordRequest(password="NewSecurePassword123!"),
)

verify_email(token) async

Verify email address using verification token.

Parameters:

Name	Type	Description	Default
token	str	Email verification token from email	required

Returns:

Type	Description
UserOut	Verified user information

Raises:

Type	Description
ValidationError	If token is invalid or expired

Example

user = await client.auth.verify_email(token="verification-token")
print(user.email)