Laravel Sanctum: token and cookie auth for SPAs and simple APIs

What problem Sanctum solves, and who it is for

The README opens with one sentence: "Laravel Sanctum provides a featherweight authentication system for SPAs and simple APIs." That sentence is the whole scope. The package exists for two situations that used to require two different solutions. The first is a first party single page application, where the browser runs JavaScript that calls your own Laravel routes. The second is a simple API, where a script, a mobile app or an internal service needs a credential that identifies a user without a browser session.

Sanctum is for people already inside Laravel. It ships as a Composer package with a service provider, a config file and migrations, and it plugs into the framework's existing authentication guards. If your backend is not Laravel, nothing here applies to you. If your clients are third parties who need to ask your users for permission to read their data, Sanctum is also the wrong shape, because the package is about your own users talking to your own application.

How Sanctum works: two credential types, one guard

The repository layout tells you most of the architecture. There is a src/ directory with the package source, a config/ directory holding a sanctum.php config file, and a database/ directory holding migrations. That combination is the mechanism: the package persists credentials in your database and exposes them through Laravel's guard system.

The first credential type is the personal access token. A token is issued to a user, stored in a database table created by the package's migrations, and sent by the client on each request. The second is the stateful cookie session, aimed at SPAs running on a domain you control. In that mode the SPA authenticates through Laravel's normal session flow, and Sanctum decides whether an incoming request from a known front end domain should be treated as a stateful, session backed request rather than a token request. The config file in config/ is where that domain list and the relevant guard settings live.

Because both paths route through the same guard, your route definitions do not need to know which one a given client used. The trade-off is that the behaviour of your API now depends on configuration: a request is treated as stateful or stateless depending on the front end domain and the guard setup, and that decision is not visible in the route file. When authentication behaves differently between a browser and curl, this split is usually why.

Installing Sanctum and issuing a first token

The README does not contain installation steps. It points to the Laravel website for documentation, at laravel.com/docs/sanctum, and that is where the setup instructions live. The package is published on Packagist as laravel/sanctum, so Composer is the install path, and the README links to that Packagist page.

The README itself gives no command to run, so the only install step that can be quoted from the repository is the package name. Follow the Laravel documentation for the exact sequence: publishing the package's configuration, running its migrations, and registering its middleware. Once the migrations run you should see the package's token table in your database and a config/sanctum.php file in your application. The README also does not show the token creation call, so follow the documentation for the exact method name and return value. The plain text token is returned once, at creation time; your client sends it back as a bearer token on subsequent requests, and the route protected by the Sanctum guard resolves the user. If the token is rejected, check the guard name in config/sanctum.php against the guard your route actually uses before changing anything else.

Where Sanctum stops being the right tool

Sanctum does not implement OAuth2. There is no authorization code flow, no refresh token exchange, no consent screen and no scope negotiation between a client and a resource owner. If you are building an integration platform where customers register their own applications and ask your users for permission, you need an OAuth2 server package, not this one.

The second limitation is structural. The stateful SPA mode assumes the front end and the API share a domain relationship you control, because it depends on a configured list of front end domains and on session cookies. An SPA hosted on an arbitrary customer domain cannot use that path, and falling back to tokens changes the security properties of the client, since a token in browser storage is exposed to any script running on the page.

The third is operational. Tokens are rows in your database. There is no central revocation service and no automatic expiry policy in the package itself; expiry and cleanup are things your application has to decide. The README does not document rollback or token cleanup procedures, so treat those as application responsibilities rather than package features.

Sanctum compared with Passport's OAuth2 approach

The obvious alternative inside the same ecosystem is Laravel Passport, which implements a full OAuth2 server. The difference is not size, it is the model of trust. Sanctum assumes the client belongs to you: your SPA, your mobile app, your script. Passport assumes the client is a separate party that needs a standardised, revocable grant from a user.

That difference shows up in what you have to build. With Sanctum, a token is a database row tied to a user, and issuing one is a method call. With Passport, you register clients, run an authorization flow, handle redirect URIs and manage grant types. For a first party SPA that is a large amount of machinery for no benefit, which is why Sanctum is the default recommendation for that case in the Laravel documentation. For a public API with third party consumers, the extra machinery is the point, and Sanctum will not substitute for it.

A second alternative is writing your own token table and middleware. Sanctum's advantage there is that it already integrates with Laravel's guard and middleware system, so you get the framework's existing authentication plumbing instead of a parallel one. The cost is that you inherit the package's assumptions about domains, guards and configuration.

Maintenance status, licence and upgrade cost

The repository is not archived, and the last push was on 2026-09-17. The most recent tagged release is v4.3.3, dated 2026-07-21, preceded by v4.3.2 on 2026-05-05 and v4.3.1 on 2026-02-10. The default branch is 4.x, so the current line is version 4, and older major versions are not the branch under development.

Upgrades are a real cost to plan for. The repository includes an UPGRADE.md file at the top level, which is the document to read before moving between major versions; its existence implies that major upgrades have required manual changes in the past. The package also ships a CHANGELOG.md, and the presence of phpstan.neon.dist and phpunit.xml.dist at the top level indicates static analysis and a test suite are part of the repository, which is a signal about how changes are checked rather than a guarantee about your application.

The licence is MIT, stated in the README and stored in LICENSE.md. That is permissive: you can use the package in commercial and closed source applications. It also means the software comes with no warranty, and the README's security section directs vulnerability reports to the repository's security policy rather than to an SLA. This is a description of the licence text, not legal advice; if your organisation has licence review requirements, the MIT text in LICENSE.md is the document to review.

Editorial conclusion

Adopt Sanctum when your front end is a first party SPA or mobile client that talks to a Laravel backend, and when you want one package to cover both cookie sessions and API tokens. Do not adopt it as a general OAuth2 server: there is no authorization code flow, no consent screen and no scope negotiation, so third party clients that need delegated access belong on a different package. Before you commit, check the config/sanctum.php file in the repository against the version of the Laravel documentation you are reading, confirm which guard your application actually uses, and read UPGRADE.md before moving between major versions.

Frequently asked questions

Official sources

1. laravel/sanctum on GitHub
2. License: MIT
3. Project website
4. README
5. Releases