Authentication

Verify a plain-text password against a stored hash.

Supports verification of both the preferred pbkdf2_sha256 hashes and legacy bcrypt hashes.

Parameters:

Name	Type	Description	Default
`plain_password`	`str`	Candidate password in plain text.	required
`hashed_password`	`str`	Stored password hash.	required

Returns:

Name	Type	Description
`bool`	`bool`	`True` if the password matches the hash, otherwise `False`.

Hash a password for storage.

New passwords are hashed using the preferred pbkdf2_sha256 scheme. Legacy bcrypt hashes remain verifiable for backward compatibility.

Parameters:

Name	Type	Description	Default
`password`	`str`	Plain-text password.	required

Returns:

Name	Type	Description
`str`	`str`	A password hash suitable for storing in the database.

Notes

The hashing scheme is managed by Passlib via pwd_context. Applications should always store the returned hash and never store raw passwords.

Create a signed JWT access token.

The token includes an expiration claim (exp). If expires_delta is not provided, the default lifespan is 30 minutes.

Parameters:

Name	Type	Description	Default
`data`	`dict`	Payload to encode into the token. Common claims include: - `sub`: subject (user id or email) - `role` / `scopes`: authorization context	required
`expires_delta`	`Optional[timedelta]`	Optional token lifespan override.	`None`

Returns:

Name	Type	Description
`str`	`str`	Encoded JWT string.

Examples:

Basic usage:

token = create_access_token({"sub": str(user.id)})
payload = decode_access_token(token)
assert payload and payload["sub"] == str(user.id)

Security

Decode and validate a JWT access token.

Validates the signature and expiry (exp). Returns None if the token is invalid, expired, or cannot be decoded.

Parameters:

Name	Type	Description	Default
`token`	`str`	Encoded JWT string (e.g. from an Authorization header).	required

Returns:

Type	Description
`Optional[dict]`	Optional[dict]: Decoded token payload, or `None` if invalid.

Notes

This function does not enforce any required claims beyond signature/expiry. Application code should validate expected fields (e.g. sub).

Examples:

payload = decode_access_token(token)
if payload:
    user_id = payload["sub"]