Install Laravel Passport and run migration and key generation commands; 2. Introduce HasApiTokens trait in the User model; 3. Register Passport routes in AuthServiceProvider; 4. Configure the API authentication guard to use the passport driver; 5. Distribute tokens through personal access tokens or password grant types; 6. Use the auth:api middleware to protect API routing; 7. Optionally configure token scopes to implement permission control; 8. Handle the refresh of access tokens to obtain new tokens; 9. Support token revocation for enhanced security; 10. Correctly configure CORS and adopt stateless authentication to ultimately implement a safe and reliable API authentication mechanism.

Handling API authentication in Laravel using Laravel Passport is straightforward once you understand the flow. Passport gives you a full OAuth2 server implementation out of the box, making it ideal for securing APIs, especially when building SPAs, mobile apps, or third-party clients.

Here's how to set up and handle API authentication with Laravel Passport:

1. Install and Setup Laravel Passport

First, install Passport via Composer:

 composer requires laravel/passport

Then, run the migrations to create the necessary tables (clients, tokens, etc.):

 php artisan migrate

Next, generate the encryption keys needed to generate secure access tokens:

 php artisan passport:install

This command creates personal access and password grant clients and their encryption keys.

?? Note: In production, never commit the keys generated by passport:install . Use php artisan passport:keys if you need to regenerate them on the server.

2. Configure Your User Model

Your User model must use the Laravel\Passport\HasApiTokens trait:

 use Laravel\Passport\HasApiTokens;

class User extends Authenticatable
{
    use HasApiTokens, Notifiable;
}

3. Register Passport Routes

In AuthServiceProvider , boot Passport and register its routes:

 use Laravel\Passport\Passport;

public function boot()
{
    $this->registerPolicies();

    Passport::routes();
}

These routes handle token issue and revocation.

4. Configure API Authentication Guard

Ensure your api guard in config/auth.php uses the passport driver:

 'guards' => [
    'api' => [
        'driver' => 'passport',
        'provider' => 'users',
    ],
],

5. Issue Tokens to Clients

Passport supports several OAuth2 grant types. The most common ones:

a) Personal Access Tokens (for trusted clients)

Useful for testing or first-party apps (eg, CLI tools). Users generate tokens via the UI.

In your controller or Tinker:

 $user = User::find(1);
$token = $user->createToken('Token Name')->accessToken;
return ['access_token' => $token];

b) Password Grant (for first-party apps like mobile apps)

This flow lets users log in with email/password and receive an access token.

First, create a password grant client:

 php artisan passport:client --password

Then, request a token from your frontend or client:

 POST /oauth/token
Content-Type: application/json

{
  "grant_type": "password",
  "client_id": "your-password-client-id",
  "client_secret": "your-password-client-secret",
  "username": "user@example.com",
  "password": "password",
  "scope": ""
}

You'll get a JSON response with access_token , refresh_token , and expiry.

? Always use HTTPS for token requests.

6. Protect API Routes

Use the auth:api middleware to protect routes:

 Route::middleware('auth:api')->get('/user', function (Request $request) {
    return $request->user();
});

Or in a controller:

 public function __construct()
{
    $this->middleware('auth:api');
}

7. Handle Token Scopes (Optional)

Scopes let you define fine-grained permissions.

Define scopes in AuthServiceProvider :

 Passport::tokensCan([
    'read-profile' => 'Read user profile',
    'update-profile' => 'Update user profile',
]);

Attach scopes to tokens during issue (eg, in password grant request):

 "scope": "read-profile update-profile"

Then protect routes by scope:

 Route::get('/profile', function () {
    // Must have 'read-profile' scope
})->middleware('scopes:read-profile');

Or check in code:

 if ($request->user()->tokenCan('update-profile')) { ... }

8. Token Expiry and Refresh

Access tokens expire (default: 1 year for personal tokens, 1 hour for password grant). Use the refresh_token to get a new access token:

 POST /oauth/token
{
  "grant_type": "refresh_token",
  "refresh_token": "your-refresh-token",
  "client_id": "client-id",
  "client_secret": "client-secret",
  "scope": ""
}

9. Revoke Tokens

To revoke a token:

 $accessToken = Auth::user()->token();
$accessToken->revoke();

Or use the revocation endpoint if enabled.

10. CORS and Frontend Considerations

If your frontend is on a different domain, configure CORS properly using Laravel Sanctum or a package like fruitcake/laravel-cors .

Also, consider using stateless authentication — Passport works statelessly with bearer tokens, so no session is needed.

In short:

• Use personal access tokens for testing/trusted clients.
• Use password grant for first-party apps (mobile/web).
• Always protect routes with auth:api .
• Use scopes for permission control.
• Handle token refresh and revocation.

With Passport, Laravel makes OAuth2 manageable without needing to write boilerplate.

Basically, once it's set up, it just works.

The above is the detailed content of How to handle API authentication with Laravel Passport?. For more information, please follow other related articles on the PHP Chinese website!