Weave Code
Sanctum Laravel Package
laravel/sanctum
Laravel Sanctum is a lightweight authentication package for Laravel, designed for SPAs and simple APIs. It supports secure session-based auth for first-party SPAs and personal access tokens for API clients with minimal setup.
Laravel Sanctum provides a featherweight authentication system for SPAs and simple APIs.
Frequently asked questions about Sanctum
- What Laravel versions does Sanctum support, and how do I check compatibility?
- Sanctum v4.x requires Laravel 11.x or later. Always check the [Packagist page](https://packagist.org/packages/laravel/sanctum) for the latest version and its Laravel requirements. Use `composer require laravel/sanctum` with `--with-all-dependencies` to ensure compatibility. If upgrading Laravel, verify Sanctum’s changelog for breaking changes.
- How do I secure Sanctum tokens in production? Are there best practices for token expiration?
- Enable token expiration by setting `stateful_expiration_in_minutes` in `config/sanctum.php`. For stateless tokens, enforce short-lived durations (e.g., 1 hour) and use `last_used_at` checks via middleware. Store tokens in HTTP-only cookies for stateful requests to mitigate XSS risks. Avoid storing tokens in localStorage for SPAs unless encrypted.
- Can Sanctum handle mobile app authentication, or do I need OAuth2 (like Passport)?
- Sanctum is ideal for mobile apps via stateless personal access tokens. It avoids OAuth2’s complexity while supporting token revocation and expiration. For third-party integrations (e.g., social logins), use Passport instead. Sanctum’s lightweight design makes it perfect for mobile backends where simplicity is key.
- How do I integrate Sanctum with a React/Vue SPA? What about CORS and CSRF?
- For SPAs, use Sanctum’s stateful mode with cookies. Configure `stateful_domain` in `config/sanctum.php` to match your frontend domain (e.g., `myapp.test`). Enable CORS with `Access-Control-Allow-Credentials: true` in your Laravel middleware. Sanctum automatically handles CSRF for stateful requests via cookies.
- What’s the performance impact of Sanctum’s token queries at scale? Can I optimize them?
- Sanctum uses `where('tokenable_id', $id)->where('token', $token)` queries, which can slow down under heavy load. Ensure the `personal_access_tokens` table has indexes (Sanctum v4.2.0+ adds them by default). For high-scale APIs, consider caching frequently accessed tokens or using a dedicated token service.
- How do I revoke or rotate tokens programmatically? Is there a built-in solution?
- Sanctum provides `token()->revoke()` to manually revoke tokens. For rotation, implement a scheduled job to generate new tokens and invalidate old ones. Track `last_used_at` to detect stale tokens. There’s no built-in rotation system, but you can extend Sanctum’s `PersonalAccessToken` model to add custom logic.
- Can I use Sanctum for internal APIs or microservices? What about multi-tenant setups?
- Yes, Sanctum works well for internal APIs and microservices. For multi-tenancy, scope tokens to tenants via `tokenable_id` (e.g., store tenant ID in the user model). Use middleware to validate tenant context before processing requests. Sanctum’s stateless design aligns perfectly with microservice architectures.
- How do I test Sanctum authentication in Laravel’s testing environment?
- Use Laravel’s `actingAs` helper with Sanctum tokens: `$user = User::factory()->create(); $token = $user->createToken('test-token'); $response = $this->withHeader('Authorization', 'Bearer '.$token)->get('/api/endpoint');`. For stateful tests, use cookies: `$this->withCookie('laravel_sanctum', $token)->get('/api/endpoint');`.
- What alternatives to Sanctum exist for Laravel APIs? When should I choose Passport over Sanctum?
- Alternatives include Passport (for OAuth2), Tymon/JWT-Auth (for JWT), or custom solutions like Sanctum + JWT. Choose Passport if you need OAuth2 (e.g., third-party logins, refresh tokens). Sanctum is better for SPAs, mobile apps, or simple APIs where OAuth2 is overkill. Sanctum’s stateless tokens are lighter and easier to maintain.
- How do I customize Sanctum’s token generation or validation logic?
- Override Sanctum’s methods like `createToken()` on your user model or extend the `PersonalAccessToken` model. For custom validation, use `getAccessTokenFromRequestUsing()` in a middleware or service provider. You can also modify token payloads by extending Sanctum’s `Token` class or using middleware to inject claims.
Weaver
How can I help you explore Laravel packages today?