Protocols

fastauth.core.protocols.UserAdapter

Bases: Protocol

Protocol for reading and writing user records.

Implement this interface to integrate FastAuth with any data store. The :class:~fastauth.adapters.sqlalchemy.SQLAlchemyAdapter provides a ready-made implementation; for testing use :class:~fastauth.adapters.memory.MemoryUserAdapter.

---

fastauth.core.protocols.SessionAdapter

Bases: Protocol

Protocol for persisting server-side sessions (session_strategy="database").

---

fastauth.core.protocols.TokenAdapter

Bases: Protocol

Protocol for persisting one-time tokens (email verification, password reset).

---

fastauth.core.protocols.OAuthAccountAdapter

Bases: Protocol

Protocol for persisting linked OAuth provider accounts.

---

fastauth.core.protocols.RoleAdapter

Bases: Protocol

Protocol for managing roles and permissions (RBAC).

---

fastauth.core.protocols.SessionBackend

Bases: Protocol

Protocol for key-value session storage (OAuth state, server sessions).

---

fastauth.core.protocols.EmailTransport

Bases: Protocol

Protocol for sending transactional emails.

---

fastauth.core.protocols.EventHooks

Base class for FastAuth lifecycle hooks.

Subclass and override whichever events you care about, then pass an instance as FastAuthConfig.hooks.

Example

from fastauth.core.protocols import EventHooks
from fastauth.types import UserData

class MyHooks(EventHooks):
    async def on_signup(self, user: UserData) -> None:
        await send_welcome_email(user["email"])

    async def modify_jwt(self, token: dict, user: UserData) -> dict:
        token["plan"] = await get_user_plan(user["id"])
        return token

config = FastAuthConfig(..., hooks=MyHooks())

on_signup async

on_signup(user: UserData) -> None

Called after a new user is created.

Parameters:

Name	Type	Description	Default
user	UserData	The newly created user record.	required

on_signin async

on_signin(user: UserData, provider: str) -> None

Called after a successful sign-in.

Parameters:

Name	Type	Description	Default
user	UserData	The authenticated user.	required
provider	str	Provider ID (e.g. "credentials", "google").	required

on_signout async

on_signout(user: UserData) -> None

Called after a user signs out.

Parameters:

Name	Type	Description	Default
user	UserData	The user who signed out.	required

on_token_refresh async

on_token_refresh(user: UserData) -> None

Called after a token pair is refreshed.

Parameters:

Name	Type	Description	Default
user	UserData	The user whose tokens were refreshed.	required

on_email_verify async

on_email_verify(user: UserData) -> None

Called after a user successfully verifies their email address.

Parameters:

Name	Type	Description	Default
user	UserData	The user whose email was verified.	required

on_password_reset async

on_password_reset(user: UserData) -> None

Called after a user successfully resets their password.

Parameters:

Name	Type	Description	Default
user	UserData	The user who reset their password.	required

on_oauth_link async

on_oauth_link(user: UserData, provider: str) -> None

Called after an OAuth account is linked to an existing user.

Parameters:

Name	Type	Description	Default
user	UserData	The user who linked the account.	required
provider	str	The OAuth provider ID (e.g. "google").	required

allow_signin async

allow_signin(user: UserData, provider: str) -> bool

Gate hook — return False to block sign-in for a specific user.

Runs before the session or token is issued. Returning False causes FastAuth to respond with HTTP 403.

Parameters:

Name	Type	Description	Default
user	UserData	The user attempting to sign in.	required
provider	str	The provider being used.	required

Returns:

Type	Description
bool	True to allow sign-in, False to deny it.

modify_session async

modify_session(
    session: dict[str, Any], user: UserData
) -> dict[str, Any]

Mutate the database session payload before it is persisted.

Only called when session_strategy="database".

Parameters:

Name	Type	Description	Default
session	dict[str, Any]	The default session dict.	required
user	UserData	The authenticated user.	required

Returns:

Type	Description
dict[str, Any]	The (possibly modified) session dict.

on_magic_link_sent async

on_magic_link_sent(user: UserData) -> None

Called after a magic link email has been dispatched to a user.

Parameters:

Name	Type	Description	Default
user	UserData	The user the magic link was sent to.	required

modify_jwt async

modify_jwt(
    token: dict[str, Any], user: UserData
) -> dict[str, Any]

Mutate the JWT payload before it is signed.

Use this to embed extra claims such as roles, permissions, or subscription tiers directly in the token so downstream services don't need a database lookup.

Parameters:

Name	Type	Description	Default
token	dict[str, Any]	The default token payload (includes sub, type, exp).	required
user	UserData	The authenticated user.	required

Returns:

Type	Description
dict[str, Any]	The (possibly modified) token payload.

---