Authentication

Authentication answers “who is this request?” Almasix uses guards (how credentials are checked — session cookie, API token, …), providers (how users are loaded from the database), and the auth() helper as the request-scoped entry point.

Browser apps usually rely on the session guard (with CSRF and Session on the web middleware group). JSON APIs typically use the token guard on the api group and stay stateless.

Config

Scaffolded by almasix new:

config = {
    "defaults": {"guard": "web", "passwords": "users"},
    "guards": {
        "web": {"driver": "session", "provider": "users"},
        "api": {"driver": "token", "provider": "users"},
    },
    "providers": {
        "users": {
            "driver": "articulate",
            "model": "app.models.user.User",
        },
    },
    "password_timeout": 10800,
}

Retrieving the user

from almasix.auth import auth

user = auth().user()
auth().check()
auth().guest()
auth().id()
auth().guard("api").user()

# Same idea via the Request bag
request.user()
request.user("api")

Prism @auth / @guest read auth_user / __authenticated shared by AuthServiceProvider.

ok = await auth().attempt(
    {"email": email, "password": password},
    remember=True,
)
if not ok:
    # auth.failed translation
    ...
await auth().logout()

With remember=True, Almasix rotates the user’s remember_token and queues a long-lived remember_{guard} cookie ({id}|{token}). EncryptCookies encrypts it; StartAuth hydrates the session from that cookie when no login payload exists. Logout clears the cookie and nulls the token.

Passwords are verified with Hash. On success, Almasix rehashes when Hash.needs_rehash says the work factor changed.

Failed and successful attempts dispatch auth events (Attempting, Validated, Login, Failed, Logout, …) — listen with almasix.auth.listen.

Intended URL

Unauthenticated browser hits on auth middleware store url.intended in the session and redirect to /login. After attempt(), redirect with pull_intended_url("/").

Protecting routes

Route.get("/settings", [SettingsController, "edit"], middleware=["auth"])
Route.get("/login", [AuthController, "show"], middleware=["guest"])
Route.get("/admin", ..., middleware=["auth:web"])
Route.get("/api/me", ..., middleware=["auth:api"])

Alias	Role
`auth` / `auth:guard`	Require authentication
`guest`	Redirect if already authenticated
`password.confirm`	Require recent password confirmation
`auth.basic`	HTTP Basic (`email` + password by default)
`verified`	Require `has_verified_email()` (MustVerifyEmail)

Unauthenticated JSON/API clients receive 401; browser web routes redirect to /login. Unknown bearer tokens do not invent a guest identity — only a provider hit authenticates the api guard.

For personal access tokens, SPA cookie auth, abilities, and mobile Bearer flows, see API Tokens (auth:signet). The classic driver: "token" / users.api_token column remains for simple demos.

Email verification

from almasix.auth import AuthenticatableMixin
from almasix.notifications import MustVerifyEmail, Notifiable
from almasix.orm import Model

class User(AuthenticatableMixin, Notifiable, MustVerifyEmail, Model):
    fillable = ("email", "name", "password", "email_verified_at")

await user.send_email_verification_notification()
await user.mark_email_as_verified()
user.has_verified_email()

Protect routes with middleware=["auth", "verified"]. Password-reset delivery uses ResetPasswordNotification by default — see Notifications and Passwords.

viaRequest

from almasix.auth import auth

auth().via_request("custom", lambda request: lookup(request))

User model

from almasix.auth import AuthenticatableMixin
from almasix.notifications import MustVerifyEmail, Notifiable
from almasix.orm import Model

class User(AuthenticatableMixin, Notifiable, MustVerifyEmail, Model):
    fillable = ("email", "name", "password", "remember_token", "api_token", "email_verified_at")
    hidden = ("password", "remember_token")