ADR 0004: Authentication strategy (session, Sanctum, magic links)

Status: Accepted
Date: 2025-10-21

Context

Wedissimo serves multiple clients and interaction patterns:

Browser-based admin and dashboard UIs (Livewire/Blade)
Public API consumers and integrations
Low-friction, email-based flows (e.g. enquiry-driven onboarding)

A single authentication mechanism would either be awkward for some flows or require complex workarounds.

Decision

Adopt a multi-strategy authentication approach:

Session-based auth (web guard) for Livewire/Blade UIs and admin tooling
Sanctum token auth (auth:sanctum) for API consumers needing bearer tokens
Magic links (passwordless, via the MagicLink module) for low-friction login and enquiry-driven flows

Guidelines:

Use session auth for internal dashboards and browser-based management tools
Use Sanctum for first-party SPAs and third-party integrations
Use magic links anywhere we want "click to continue" behaviour without passwords (e.g. follow-up after sending an enquiry)

Consequences

Positive

Each use case can use the auth strategy that fits best
Passwordless flows align with low-friction account creation
Sanctum provides a Laravel-native way to manage API tokens

Negative / trade-offs

More concepts to understand for new developers (three auth strategies instead of one)
Configuration complexity across guards, providers, and middleware
Need to ensure a consistent user identity model across strategies