Sanctum Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require laravel/sanctum
   php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"
   php artisan migrate
   

   • Publishes Sanctum’s configuration, migrations, and routes.
   • Runs migrations to create personal_access_tokens table.

2. Configure Middleware: Add Sanctum’s middleware to app/Http/Kernel.php:

   'api' => [
       \Laravel\Sanctum\Http\Middleware\EnsureFrontendRequestsAreStateful::class,
       'throttle:api',
       \Illuminate\Routing\Middleware\SubstituteBindings::class,
   ],
   

   For API routes, use auth:sanctum middleware.

3. First Use Case:

   • SPA Authentication:

     // Frontend (e.g., React/Vue)
     const response = await fetch('/api/user', {
       headers: { 'Authorization': `Bearer ${token}` }
     });
     

   • API Endpoint:

     // Laravel Controller
     public function user(Request $request) {
         return $request->user(); // Authenticated user
     }
     

4. Key Files:

   • config/sanctum.php: Configure stateful domains, token expiration, and guards.
   • app/Models/User.php: Ensure HasApiTokens trait is used.

Implementation Patterns

1. Token Management

• Generating Tokens:

  // For a User model
  $token = $user->createToken('app-name')->plainTextToken;
  

  • Use createToken() with a descriptive name (e.g., mobile-app, admin-dashboard).
  • Store tokens securely (e.g., in frontend state or encrypted storage).

• Revocating Tokens:

  $user->tokens()->where('name', 'app-name')->delete();
  

  • Revoke by token name or ID for granular control.

• Token Scopes:

  $token = $user->createToken('admin')->scopes(['manage']);
  

  • Assign scopes to restrict access (e.g., authorize:manage).

2. Stateful vs. Stateless APIs

• Stateful (SPAs):

  • Configure stateful domains in config/sanctum.php:

    'stateful' => explode(',', env('SANCTUM_STATEFUL_DOMAINS', 'localhost,127.0.0.1')),
    

  • Use EnsureFrontendRequestsAreStateful middleware to validate CSRF tokens for frontend requests.

• Stateless (Mobile/APIs):

  • Use auth:sanctum middleware without stateful checks.
  • Tokens are validated via Authorization: Bearer <token> header.

3. Customizing Token Retrieval

• Override default token resolution:

  // In AppServiceProvider@boot()
  Sanctum::getAccessTokenFromRequestUsing(function ($request) {
      return $request->bearerToken() ?: $request->cookie('sanctum');
  });
  

  • Useful for custom auth headers (e.g., X-Auth-Token).

4. Testing

• Mock Auth:

  $user = User::factory()->create();
  Sanctum::actingAs($user);
  

• Token Testing:

  $response = $this->withHeaders([
      'Authorization' => 'Bearer ' . $user->createToken('test')->plainTextToken,
  ])->get('/api/endpoint');
  

5. Integration with Passport (Optional)

• Sanctum is lightweight; use Passport for OAuth2 if needed.
• Sanctum tokens are shorter and simpler for SPAs/APIs.

Gotchas and Tips

Pitfalls

1. CSRF Token Mismatches:

   • Stateful requests (e.g., SPAs) require CSRF tokens. Ensure:
     • XSRF-TOKEN cookie is set.
     • EnsureFrontendRequestsAreStateful middleware is applied.
   • Debug: Check sanctum.stateful_domains in config and frontend meta tags.

2. Token Expiration:

   • Tokens expire after 1 year by default. Customize in config/sanctum.php:

     'expiration' => now()->addDays(30),
     

   • Use last_used_at tracking (v4.3.0+) to invalidate stale tokens:

     Sanctum::enableTokenTracking(); // In AppServiceProvider
     

3. Database Indexes:

   • Sanctum adds indexes to personal_access_tokens (v4.2.0+). Ensure your DB supports them.
   • For large-scale apps, monitor token lookup performance.

4. Token Prefix Collisions:

   • Tokens use a prefix/checksum format. Avoid custom token generation that conflicts with Sanctum’s logic.

5. Middleware Order:

   • Place EnsureFrontendRequestsAreStateful before auth:sanctum in your middleware stack.

Debugging Tips

• Token Validation Errors:

  • Check sanctum.token_blacklist table if tokens are revoked but still valid.
  • Verify token format: Bearer <60-character-token>.

• Logging:

  • Enable Sanctum logs in config/logging.php:

    'channels' => [
        'sanctum' => [
            'driver' => 'single',
            'path' => storage_path('logs/sanctum.log'),
            'level' => 'debug',
        ],
    ],
    

• Common Issues:

  • 401 Unauthorized: Token missing/invalid. Verify Authorization header.
  • 419 CSRF Token Mismatch: Frontend request lacks XSRF-TOKEN cookie.
  • 429 Too Many Requests: Throttling middleware (e.g., throttle:api) is active.

Extension Points

1. Custom Token Models:

   • Extend HasApiTokens for custom token logic:

     use Laravel\Sanctum\HasApiTokens;
     
     class User extends Authenticatable {
         use HasApiTokens;
     
         public function createCustomToken($name) {
             return $this->createToken($name)->tap(function ($token) {
                 $token->forceFill(['custom_field' => 'value']);
             });
         }
     }
     

2. Token Events:

   • Listen to token creation/revocation:

     // In EventServiceProvider
     protected $listen = [
         \Laravel\Sanctum\Events\TokenCreated::class => [
             \App\Listeners\LogTokenCreation::class,
         ],
     ];
     

3. Custom Guards:

   • Register a custom guard in AuthServiceProvider:

     Sanctum::guard('custom', function () {
         return new CustomGuard();
     });
     

4. Token Metadata:

   • Attach metadata to tokens:

     $token = $user->createToken('app', ['read'], 30); // 30-minute expiry
     $token->metadata = ['device' => 'mobile'];
     $token->save();
     

Performance

• Token Lookup:

  • Sanctum uses crc32b for checksums (v3.3.0+). Ensure your DB indexes support this.
  • For high traffic, consider caching token validation (e.g., Redis):

    Sanctum::useTokenCache(function ($token) {
        return Cache::remember("sanctum-{$token->id}", now()->addMinutes(5), function () use ($token) {
            return $token->user;
        });
    });
    

• Database Optimization:

  • Add indexes manually if needed:

    Schema::table('personal_access_tokens', function (Blueprint $table) {
        $table->index(['tokenable_id', 'tokenable_type']);
        $table->index('created_at');
    });
    

Security

• Token Storage:

  • Never store tokens in localStorage (XSS risk). Use HttpOnly cookies or secure backend storage.
  • Example for cookies:

    Sanctum::statefulDomain('yourdomain.com');
    Sanctum::cookie($token, 'sanctum', now()->addDays(30));
    

• Rate Limiting:

  • Combine with Laravel’s throttling:

    Route::middleware(['throttle:60,1', 'auth:sanctum'])->get('/api/endpoint');
    

• Sensitive Data:

  • Avoid exposing user data in token names (e.g., user-123). Use generic names like mobile-app.