# `PhoenixKit.Users.Auth.UserToken`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.164/lib/phoenix_kit/users/auth/user_token.ex#L1)

User token schema for PhoenixKit authentication system.

This schema handles various types of tokens used for user authentication and verification:

## Token Types

- **Session tokens**: For maintaining user sessions (60 days validity)
- **Email confirmation tokens**: For account verification (7 days validity)
- **Password reset tokens**: For secure password recovery (1 hour validity)
- **Email change tokens**: For confirming new email addresses (7 days validity)
- **Magic link tokens**: For passwordless authentication (15 minutes validity per industry security standards)

## Security Features

- Tokens are hashed using SHA256 before storage
- Different expiry policies for different token types
- Secure random token generation (48 bytes for enhanced security)
- Context-based token management for isolation
- Short-lived magic links (15 minutes) minimize security exposure

# `build_email_token`

Builds a token and its hash to be delivered to the user's email.

The non-hashed token is sent to the user email while the
hashed part is stored in the database. The original token cannot be reconstructed,
which means anyone with read-only access to the database cannot directly use
the token in the application to gain access. Furthermore, if the user changes
their email in the system, the tokens sent to the previous email are no longer
valid.

Users can easily adapt the existing code to provide other types of delivery methods,
for example, by phone numbers.

# `build_email_token_for_context`

Generates a token for email-based operations without requiring a user struct.

This is useful for pre-registration flows like magic link registration where
the user doesn't exist yet.

## Examples

    iex> build_email_token_for_context("user@example.com", "magic_link_registration")
    {"encoded_token", %UserToken{}}

# `build_session_token`

Generates a token that will be stored in a signed place,
such as session or cookie. As they are signed, those
tokens do not need to be hashed.

The reason why we store session tokens in the database, even
though Phoenix already provides a session cookie, is because
Phoenix' default session cookies are not persisted, they are
simply signed and potentially encrypted. This means they are
valid indefinitely, unless you change the signing/encryption
salt.

Therefore, storing them allows individual user
sessions to be expired. The token system can also be extended
to store additional data, such as the device used for logging in.
You could then use this information to display all valid sessions
and devices in the UI and allow users to explicitly expire any
session they deem invalid.

## Session Fingerprinting

The token can optionally include session fingerprinting data to prevent
session hijacking. Pass a `fingerprint` option with `ip_address` and
`user_agent_hash` to enable this feature.

## Options

  * `:fingerprint` - A `%SessionFingerprint{}` struct with `:ip_address` and `:user_agent_hash` fields

## Examples

    # Without fingerprinting (backward compatible)
    {token, user_token} = build_session_token(user)

    # With fingerprinting
    fingerprint = SessionFingerprint.create_fingerprint(conn)
    {token, user_token} = build_session_token(user, fingerprint: fingerprint)

# `by_token_and_context_query`

Returns the token struct for the given token value and context.

# `by_user_and_contexts_query`

Gets all tokens for the given user for the given contexts.

# `verify_change_email_token_query`

Checks if the token is valid and returns its underlying lookup query.

The query returns the user found by the token, if any.

This is used to validate requests to change the user
email. It is different from `verify_email_token_query/2` precisely because
`verify_email_token_query/2` validates the email has not changed, which is
the starting point by this function.

The given token is valid if it matches its hashed counterpart in the
database and if it has not expired (after @change_email_validity_in_days).
The context must always start with "change:".

# `verify_email_token_query`

Checks if the token is valid and returns its underlying lookup query.

The query returns the user found by the token, if any.

The given token is valid if it matches its hashed counterpart in the
database and the user email has not changed. This function also checks
if the token is being used within a certain period, depending on the
context. The default contexts supported by this function are either
"confirm", for account confirmation emails, and "reset_password",
for resetting the password. For verifying requests to change the email,
see `verify_change_email_token_query/2`.

# `verify_session_token_query`

Checks if the token is valid and returns its underlying lookup query.

The query returns the user found by the token, if any.

The token is valid if it matches the value in the database and it has
not expired (after @session_validity_in_days).

---

*Consult [api-reference.md](api-reference.md) for complete listing*