Laravel Sanctum

Laravel Sanctum is the official, lightweight authentication package for Laravel applications that need to authenticate single-page apps, mobile apps, or simple token-based APIs, without the complexity of a full OAuth server like Passport. It offers two authentication strategies from one package: stateful, cookie-based authentication for first-party SPAs sharing a session with the backend, and personal access tokens for third-party clients and mobile apps.

Sanctum integrates directly into Laravel’s authentication and middleware pipeline via the HasApiTokens trait and a dedicated Guard, so authenticating a request in a controller looks identical whether the caller used a session cookie or a bearer token. Tokens can be scoped with abilities (similar to OAuth scopes) to limit what actions a given token is allowed to perform.

What You Get

• The HasApiTokens trait, adding createToken(), tokens(), and ability-checking methods to any Eloquent user model
• A PersonalAccessToken model and migration for storing hashed API tokens with optional expiration and ability scopes
• A stateful SPA authentication mode that uses Laravel’s existing session/cookie guard for first-party frontends on the same top-level domain
• A custom Guard class wiring both token and session authentication into Laravel’s auth() facade transparently
• Middleware (EnsureFrontendRequestsAreStateful) that marks requests from configured frontend domains as session-authenticated instead of token-authenticated
• Console commands (sanctum:prune-expired) for cleaning up expired tokens on a schedule

Common Use Cases

• Authenticating a same-origin Vue/React/Inertia SPA against a Laravel backend using session cookies instead of tokens
• Issuing scoped personal access tokens to mobile apps or third-party API consumers
• Restricting what a given API token can do via named abilities (e.g. token->can('post:create'))
• Building a simple public API for a Laravel app without standing up a full OAuth2 server
• Pruning expired or unused tokens automatically via a scheduled console command

Under The Hood

Architecture: SanctumServiceProvider registers the package’s config, migrations, and the custom Guard (in src/Guard.php), which is invoked per-request to resolve the authenticated user — first checking configured session guards, then falling back to bearer-token lookup via getTokenFromRequest(). HasApiTokens.php is the trait consuming applications mix into their User model, exposing createToken() (returns a NewAccessToken pairing the plaintext token with its hashed PersonalAccessToken record) and ability-checking helpers. Http/Middleware/EnsureFrontendRequestsAreStateful.php flags requests from allowlisted frontend domains so the guard treats them as session-authenticated SPA traffic rather than token traffic.

Tech Stack: Pure PHP, built entirely on Laravel’s own framework contracts (Illuminate\Contracts\Auth, Eloquent) — it has no dependencies outside the Laravel ecosystem itself, since it’s designed to be installed directly into a Laravel application via composer require laravel/sanctum and its own service provider.

Code Quality: The tests/ directory (Feature and Unit suites, 14+ test files) exercises the guard’s session-vs-token resolution paths, token ability scoping, and console commands, run via Orchestra Testbench for isolated Laravel package testing. The codebase follows Laravel’s own coding conventions closely (PHPDoc blocks, PSR-style namespacing) as an official first-party package maintained by the Laravel core team.

API Design: The core ergonomic win is that auth()->user() and route middleware work identically regardless of whether the request came in with a session cookie or a bearer token — consuming applications write one auth check, and Sanctum resolves which mechanism applies underneath, which is what makes it ‘featherweight’ relative to configuring a full OAuth2 flow for the same SPA-plus-mobile-client use case.