Laravel Passport (OAuth2 server implementation)

Learn how to implement an OAuth2 server with Laravel Passport. Covers when to choose Passport versus Sanctum, installation, client management, and scope and token management.

What is Passport

Laravel Passport is the official package for running a Laravel application as an OAuth2 authorization server. Use it for third-party app integrations and APIs that require a strict OAuth2 flow.

Passport vs Sanctum

Choose Passport if OAuth2 is required. Choose Sanctum for simple API token authentication or SPA / mobile authentication.

Aspect	Passport	Sanctum
Purpose	OAuth2 server implementation	Simple API authentication
Well-suited for	External app integration, OAuth2 compliance	First-party SPA, mobile, personal-use tokens
Complexity	High	Low

Installation

The official recommendation in Laravel 13 is install:api --passport.

php artisan install:api --passport

For a manual installation on an existing project, you can also set it up with the following commands.

composer require laravel/passport
php artisan passport:install

There are cases where you only want to generate keys on the initial deployment.

php artisan passport:keys

Configuration

User model

Add the HasApiTokens trait and the OAuthenticatable interface to your User model.

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
use Laravel\Passport\Contracts\OAuthenticatable;
use Laravel\Passport\HasApiTokens;

class User extends Authenticatable implements OAuthenticatable
{
    use HasApiTokens, HasFactory, Notifiable;
}

auth guard

In the api guard of config/auth.php, use the passport driver.

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

Service provider configuration

In your AppServiceProvider’s boot() method, you can define scopes and token expirations.

use Carbon\CarbonInterval;
use Laravel\Passport\Passport;

public function boot(): void
{
    Passport::tokensCan([
        'orders:read' => 'View orders',
        'orders:create' => 'Create orders',
    ]);

    Passport::defaultScopes(['orders:read']);

    Passport::tokensExpireIn(CarbonInterval::days(15));
    Passport::refreshTokensExpireIn(CarbonInterval::days(30));
    Passport::personalAccessTokensExpireIn(CarbonInterval::months(6));
}

Client management

Authorization code grant client

php artisan passport:client

This client is used with the standard OAuth2 flow that involves a user consent screen.

Client credentials grant client

php artisan passport:client --client

For machine-to-machine endpoints, use the EnsureClientIsResourceOwner middleware.

use Laravel\Passport\Http\Middleware\EnsureClientIsResourceOwner;

Route::get('/orders', function () {
    // ...
})->middleware(EnsureClientIsResourceOwner::using('orders:read'));

Token management

Granting scopes

$accessToken = $user->createToken(
    'dashboard-token',
    ['orders:read', 'orders:create']
)->accessToken;

Checking scopes

use Laravel\Passport\Http\Middleware\CheckToken;

Route::get('/orders', function () {
    // ...
})->middleware(['auth:api', CheckToken::using('orders:read')]);

Revocation

use Laravel\Passport\Passport;

$token = Passport::token()->find($tokenId);
$token?->revoke();

Protecting API routes

Attach auth:api to APIs protected by user access tokens.

Route::middleware('auth:api')->group(function () {
    Route::get('/user', fn (Request $request) => $request->user());
    Route::get('/orders', [OrderController::class, 'index']);
});

For client credentials grant routes, use EnsureClientIsResourceOwner instead of auth:api.

Personal Access Tokens

These are well-suited to cases where the user themselves issues an API token without going through the full OAuth2 flow.

php artisan passport:client --personal

$token = $request->user()->createToken('cli-token', ['orders:read'])->accessToken;

If Personal Access Tokens are your primary use case, Laravel itself officially recommends considering Sanctum.

Related links

• Laravel official documentation: Passport
• Laravel official documentation: Sanctum