Auth Adapters

Auth ships with two built-in adapters. Both use the same auth service and shared account-flow methods, but they persist authenticated state differently.

Session adapter

Use session for browser-based applications where Quantum should keep the authenticated user in server-side session storage.

$auth = auth('session');
$auth->signin($email, $password, true);

What it does

After a successful sign-in without two-factor interruption, the adapter:

  • regenerates the PHP session ID
  • stores the authenticated user under the auth_user session key
  • stores only schema fields marked as visible

user() first reads from session storage. If no session user exists, it can restore the user from the remember-token cookie.

Remember-me behavior

Passing true as the third argument to signin() enables remember-me behavior.

The adapter then:

  • generates a remember token
  • stores that token through your auth service
  • writes the token to a cookie

The remember cookie lifetime comes from auth.session.remember_lifetime. If that setting is absent, the default is 2592000 seconds (30 days).

On sign-out, the adapter deletes the session user, regenerates the session ID, clears the stored remember token, and deletes the cookie.

Two-factor caveat

When two-factor auth is enabled, signin() returns an OTP token instead of logging the user in immediately.

If a remembered user still has a pending OTP token in storage, the adapter refuses to restore that user from the remember cookie.

JWT adapter

Use jwt for APIs where the client should carry authentication state in tokens.

$tokens = auth('jwt')->signin($email, $password);

$accessToken = $tokens['accessToken'];
$refreshToken = $tokens['refreshToken'];

What it does

After a successful sign-in without two-factor interruption, the adapter:

  • generates a refresh token and stores it through your auth service
  • creates a JWT access token from visible user fields
  • base64-encodes the signed JWT before returning it
  • writes both tokens into the current request/response objects

The response gets a tokens payload, and the request object is updated with:

  • Authorization: Bearer <base64-encoded-access-token>
  • the configured refresh-token header

User restoration and refresh fallback

user() tries the access token first.

If access-token parsing or verification fails, the adapter falls back to the refresh token header. When that header matches a stored user, Auth rotates both tokens and then retries user() with the new access token.

This means a valid refresh token can transparently refresh the current request's auth state.

Sign-out behavior

JWT sign-out depends on the refresh token header.

When sign-out succeeds, the adapter:

  • clears the stored refresh token through your auth service
  • removes the refresh-token request header
  • removes the Authorization header from the request
  • deletes the tokens response payload

If the refresh token header is missing or unknown, signout() returns false.

Choosing between them

Use session when you want classic web login state, session regeneration, and optional remember-me cookies.

Use jwt when you need API-friendly access tokens plus refresh-token-based token rotation.

Shared adapter rules

Both adapters:

  • require an auth service class configured at auth.<adapter>.service
  • validate credentials through the configured service and the Hasher package
  • reject inactive accounts
  • send activation, reset, and OTP emails through the Mailer package
  • depend on schema field mappings from userSchema()