{"id":356,"date":"2025-08-27T20:17:40","date_gmt":"2025-08-27T20:17:40","guid":{"rendered":"https:\/\/1v0.net\/blog\/?p=356"},"modified":"2025-08-27T20:17:43","modified_gmt":"2025-08-27T20:17:43","slug":"using-laravel-passport-for-advanced-api-authentication","status":"publish","type":"post","link":"https:\/\/1v0.net\/blog\/using-laravel-passport-for-advanced-api-authentication\/","title":{"rendered":"Using Laravel Passport for Advanced API Authentication"},"content":{"rendered":"\n

Using Laravel Passport for Advanced API Authentication<\/strong><\/h2>\n\n\n\n

Laravel Passport<\/strong> brings a full OAuth2 server to your Laravel app\u2014great when you need first-class features beyond simple token auth: password grants, client credentials (machine-to-machine), refresh tokens, and scopes<\/em> for fine-grained permissions. In this guide you\u2019ll install Passport, wire up guards, issue tokens via multiple grants, enforce scopes, and add a tiny UI to test flows quickly.<\/p>\n\n\n\n

<\/div>\n\n\n\n\n

1 – Install Passport & Bootstrap Keys<\/strong><\/h2>\n\n\n\n

Add Passport to your project and generate encryption keys and default clients (password & personal access).<\/p>\n\n\n

composer require laravel\/passport\n\nphp artisan migrate\nphp artisan passport:install<\/code><\/span>Code language:<\/span> Bash<\/span> (<\/span>bash<\/span>)<\/span><\/small><\/pre>\n\n\n
passport:install<\/code> creates RSA keys and seeds OAuth clients into oauth_clients<\/code>. You\u2019ll get a Password Grant Client<\/em> (for username\/password token exchange), and a Personal Access Client<\/em> for user-issued long-lived tokens (developer tooling \/ first-party use).<\/p>\n\n\n\n\n
<\/div>\n\n\n\n\n
2 – Configure Auth Guard for APIs<\/strong><\/h2>\n\n\n\n
Use Passport as the driver for the api<\/code> guard so auth:api<\/code> middleware validates OAuth2 access tokens.<\/p>\n\n\n
\/\/ config\/auth.php (snippet)<\/span>\n'guards'<\/span> => [\n    'web'<\/span> => [\n        'driver'<\/span> => 'session'<\/span>,\n        'provider'<\/span> => 'users'<\/span>,\n    ],\n    'api'<\/span> => [\n        'driver'<\/span> => 'passport'<\/span>,\n        'provider'<\/span> => 'users'<\/span>,\n    ],\n],<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
Switching the api<\/code> guard to the passport<\/code> driver makes auth:api<\/code> and Passport\u2019s scope middleware work out of the box for routes under routes\/api.php<\/code>.<\/p>\n\n\n\n
\/\/ app\/Providers\/AuthServiceProvider.php (snippet)<\/span>\nuse<\/span> Laravel<\/span>\\Passport<\/span>\\Passport<\/span>;\n\npublic<\/span> function<\/span> boot<\/span>()<\/span>: void<\/span>\n<\/span>{\n    $this<\/span>->registerPolicies();\n\n    Passport::routes(); \/\/ registers \/oauth\/* routes<\/span>\n\n    \/\/ Optional: token expiry & scopes<\/span>\n    Passport::tokensExpireIn(now()->addHours(2<\/span>));\n    Passport::refreshTokensExpireIn(now()->addDays(30<\/span>));\n\n    Passport::tokensCan([\n        'read-posts'<\/span>  => 'Read posts data'<\/span>,\n        'write-posts'<\/span> => 'Create or update posts'<\/span>,\n        'admin'<\/span>       => 'Full administrative access'<\/span>,\n    ]);\n}<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
Passport::routes()<\/code> exposes the OAuth endpoints (\/oauth\/token<\/code>, \/oauth\/authorize<\/code>, etc.). You can tune lifetimes and define named scopes<\/em> describing which capabilities a token grants.<\/p>\n\n\n\n\n
<\/div>\n\n\n\n\n
3 – Issuing Tokens via Password Grant<\/strong><\/h2>\n\n\n\n
The Password Grant<\/strong> lets first-party apps exchange a user\u2019s email+password for an access + refresh token pair. Store the client ID\/secret in env.<\/p>\n\n\nOAUTH_PASSWORD_CLIENT_ID=3\nOAUTH_PASSWORD_CLIENT_SECRET=your-password-client-secret\n\n\n
Find these values from the output of passport:install<\/code> (or in the oauth_clients<\/code> table where password_client = 1<\/code>). Keep the secret confidential.<\/p>\n\n\n\n
\/\/ app\/Http\/Controllers\/OAuth\/PasswordGrantController.php<\/span>\nnamespace<\/span> App<\/span>\\Http<\/span>\\Controllers<\/span>\\OAuth<\/span>;\n\nuse<\/span> Illuminate<\/span>\\Http<\/span>\\Request<\/span>;\nuse<\/span> Illuminate<\/span>\\Support<\/span>\\Facades<\/span>\\Http<\/span>;\n\nclass<\/span> PasswordGrantController<\/span>\n<\/span>{\n    public<\/span> function<\/span> token<\/span>(Request $request)<\/span>\n    <\/span>{\n        $request->validate([\n            'username'<\/span> => ['required'<\/span>,'email'<\/span>],\n            'password'<\/span> => ['required'<\/span>],\n            'scope'<\/span>    => ['nullable'<\/span>,'string'<\/span>], \/\/ e.g. \"read-posts write-posts\"<\/span>\n        ]);\n\n        $payload = [\n            'grant_type'<\/span>    => 'password'<\/span>,\n            'client_id'<\/span>     => config('services.passport.password_client_id'<\/span>),\n            'client_secret'<\/span> => config('services.passport.password_client_secret'<\/span>),\n            'username'<\/span>      => $request->username,\n            'password'<\/span>      => $request->password,\n            'scope'<\/span>         => $request->input('scope'<\/span>,''<\/span>),\n        ];\n\n        $response = Http::asForm()->post(url('\/oauth\/token'<\/span>), $payload);\n\n        return<\/span> response()->json($response->json(), $response->status());\n    }\n}<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
This endpoint proxies your request to Passport\u2019s \/oauth\/token<\/code> and returns the OAuth2 response (access token, refresh token, expires_in). Limit this to trusted first-party clients; never expose the password client secret to browsers you don\u2019t control.<\/p>\n\n\n\n
\/\/ config\/services.php (snippet)<\/span>\n'passport'<\/span> => [\n    'password_client_id'<\/span>     => env('OAUTH_PASSWORD_CLIENT_ID'<\/span>),\n    'password_client_secret'<\/span> => env('OAUTH_PASSWORD_CLIENT_SECRET'<\/span>),\n],\n\n\/\/ routes\/api.php (snippet)<\/span>\nuse<\/span> App<\/span>\\Http<\/span>\\Controllers<\/span>\\OAuth<\/span>\\PasswordGrantController<\/span>;\nRoute::post('\/oauth\/password\/token'<\/span>, [PasswordGrantController::class, 'token'<\/span>]);<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
Config values centralize secrets and keep controllers clean. The route exposes a first-party-only token exchange endpoint your SPA\/mobile client can call via your backend.<\/p>\n\n\n\n\n
<\/div>\n\n\n\n\n
4 – Client Credentials (M2M) Tokens<\/strong><\/h2>\n\n\n\n
For server-to-server integrations (no user), use the Client Credentials<\/strong> grant. Create a client and use its ID\/secret to fetch tokens.<\/p>\n\n\n
php artisan passport:client --client\n# copy the client_id and client_secret<\/span><\/code><\/span>Code language:<\/span> Bash<\/span> (<\/span>bash<\/span>)<\/span><\/small><\/pre>\n\n\n
This creates a confidential client for machines. Those tokens won\u2019t carry a user, so your API should check capabilities accordingly (e.g., scoped to service roles only).<\/p>\n\n\n\n
\/\/ Example: validating a client-credentials call in a controller<\/span>\n\/\/ $request->user() will be null; rely on token scopes\/claims<\/span>\npublic<\/span> function<\/span> m2mEndpoint<\/span>(Request $request)<\/span>\n<\/span>{\n    \/\/ Gate access by scope via middleware or manual check<\/span>\n    return<\/span> ['status'<\/span> => 'ok'<\/span>];\n}<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
Because there\u2019s no user context, don\u2019t assume $request->user()<\/code> exists. Protect these routes with scope middleware to limit what the machine can do.<\/p>\n\n\n\n\n
<\/div>\n\n\n\n\n
5 – Protecting Routes & Enforcing Scopes<\/strong><\/h2>\n\n\n\n
Use Passport\u2019s middleware to require a valid token and specific scopes. You can combine multiple scopes for least-privilege access.<\/p>\n\n\n
\/\/ routes\/api.php<\/span>\nuse<\/span> App<\/span>\\Http<\/span>\\Controllers<\/span>\\PostApiController<\/span>;\n\nRoute::middleware(['auth:api'<\/span>, 'scopes:read-posts'<\/span>])->get('\/posts'<\/span>, [PostApiController::class, 'index'<\/span>]);\n\nRoute::middleware(['auth:api'<\/span>, 'scopes:write-posts'<\/span>])->post('\/posts'<\/span>, [PostApiController::class, 'store'<\/span>]);\n\nRoute::middleware(['auth:api'<\/span>, 'scopes:admin'<\/span>])->delete('\/posts\/{post}'<\/span>, [PostApiController::class, 'destroy'<\/span>]);<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
auth:api<\/code> verifies the token signature and expiration. The scopes:<\/code> middleware ensures the token contains the required scope(s). Tokens without the scope will receive 403<\/code> responses.<\/p>\n\n\n\n\n
<\/div>\n\n\n\n\n
6 – Refresh Tokens & Rotation<\/strong><\/h2>\n\n\n\n
Clients should refresh before access tokens expire. Passport supports refresh tokens out of the box via the refresh_token<\/code> grant.<\/p>\n\n\n
# Example POST to \/oauth\/token (form-encoded)<\/span>\ngrant_type=refresh_token\nclient_id=...\nclient_secret=...\nrefresh_token=... (from previous token response)<\/code><\/span>Code language:<\/span> Bash<\/span> (<\/span>bash<\/span>)<\/span><\/small><\/pre>\n\n\n
On success, Passport returns a new access token (and often a new refresh token). Store tokens securely (never in localStorage for sensitive apps\u2014prefer HTTP-only cookies or native secure storage on mobile).<\/p>\n\n\n\n\n
<\/div>\n\n\n\n\n
7 – Personal Access Tokens (Developer UX)<\/strong><\/h2>\n\n\n\n
Users can manually create long-lived tokens to use in tools like Postman. Add simple endpoints to mint \/ revoke them with chosen scopes.<\/p>\n\n\n
\/\/ app\/Http\/Controllers\/PersonalTokenController.php<\/span>\nnamespace<\/span> App<\/span>\\Http<\/span>\\Controllers<\/span>;\n\nuse<\/span> Illuminate<\/span>\\Http<\/span>\\Request<\/span>;\n\nclass<\/span> PersonalTokenController<\/span> extends<\/span> Controller<\/span>\n<\/span>{\n    public<\/span> function<\/span> create<\/span>(Request $request)<\/span>\n    <\/span>{\n        $request->validate([\n            'name'<\/span>  => ['required'<\/span>,'string'<\/span>,'max:60'<\/span>],\n            'scopes'<\/span> => ['array'<\/span>],\n            'scopes.*'<\/span> => ['string'<\/span>],\n        ]);\n\n        $token = $request->user()->createToken(\n            $request->name,\n            $request->input('scopes'<\/span>, []) \/\/ e.g. ['read-posts']<\/span>\n        );\n\n        return<\/span> ['token'<\/span> => $token->accessToken];\n    }\n\n    public<\/span> function<\/span> revoke<\/span>(Request $request)<\/span>\n    <\/span>{\n        $request->user()->token()->revoke();\n        return<\/span> ['status'<\/span> => 'revoked'<\/span>];\n    }\n}<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
createToken()<\/code> issues a personal access token for the authenticated user with the requested scopes. This is convenient for CLI scripts and power users; still apply least-privilege scopes.<\/p>\n\n\n\n\n
<\/div>\n\n\n\n\n
8 – UI: OAuth Token Playground (Password Grant)<\/strong><\/h2>\n\n\n\n
Here\u2019s a tiny Blade UI that exchanges email\/password for an access token, then calls a protected endpoint with scopes.<\/p>\n\n\n
<!-- resources\/views\/oauth\/playground.blade.php -->\n@extends('layouts.app'<\/span>)\n\n@section('content'<\/span>)\n<div class<\/span>=\"container<\/span>\">\n  <h1<\/span>>OAuth<\/span> Token<\/span> Playground<\/span> (Passport<\/span>)<\/h1<\/span>>\n\n  <div<\/span> class<\/span>=\"row<\/span> g<\/span>-3\">\n    <div<\/span> class<\/span>=\"col<\/span>-md<\/span>-4\"><input<\/span> id<\/span>=\"email<\/span>\" class<\/span>=\"form<\/span>-control<\/span>\" placeholder<\/span>=\"Email<\/span>\"><\/div<\/span>>\n    <div<\/span> class<\/span>=\"col<\/span>-md<\/span>-4\"><input<\/span> id<\/span>=\"password<\/span>\" class<\/span>=\"form<\/span>-control<\/span>\" type<\/span>=\"password<\/span>\" placeholder<\/span>=\"Password<\/span>\"><\/div<\/span>>\n    <div<\/span> class<\/span>=\"col<\/span>-md<\/span>-4\"><input<\/span> id<\/span>=\"scope<\/span>\" class<\/span>=\"form<\/span>-control<\/span>\" placeholder<\/span>=\"Scopes<\/span> (space<\/span>-separated<\/span>), e<\/span>.g<\/span>. read<\/span>-posts<\/span>\"><\/div<\/span>>\n  <\/div<\/span>>\n\n  <button<\/span> class<\/span>=\"btn<\/span> btn<\/span>-theme<\/span> mt<\/span>-3\" onclick<\/span>=\"getToken<\/span>()\">Get<\/span> Token<\/span><\/button<\/span>>\n  <button<\/span> class<\/span>=\"btn<\/span> btn<\/span>-secondary<\/span> mt<\/span>-3 ms<\/span>-2\" onclick<\/span>=\"callApi<\/span>()\">Call<\/span> \/api<\/span>\/posts<\/span><\/button<\/span>>\n\n  <pre<\/span> id<\/span>=\"out<\/span>\" class<\/span>=\"mt<\/span>-3\"><\/pre<\/span>>\n<\/div<\/span>>\n\n<script<\/span> src<\/span>=\"https<\/span>:\/\/cdn<\/span>.jsdelivr<\/span>.net<\/span>\/npm<\/span>\/axios<\/span>\/dist<\/span>\/axios<\/span>.min<\/span>.js<\/span>\"><\/script<\/span>>\n<script<\/span>>\nlet<\/span> token<\/span> = null<\/span>;\n\nfunction<\/span> getToken<\/span>() <\/span>{\n  axios.post('\/api\/oauth\/password\/token'<\/span>, {\n    username: document.getElementById('email'<\/span>).value,\n    password: document.getElementById('password'<\/span>).value,\n    scope: document.getElementById('scope'<\/span>).value\n  }).then(res => {\n    token = res.data.access_token;\n    document.getElementById('out'<\/span>).textContent = JSON.stringify(res.data, null<\/span>, 2<\/span>);\n  }).catch<\/span>(err => {\n    document.getElementById('out'<\/span>).textContent = err.response ? JSON.stringify(err.response.data, null<\/span>, 2<\/span>) : err;\n  });\n}\n\nfunction<\/span> callApi<\/span>()<\/span> <\/span>{\n  if<\/span> (!token) return<\/span> alert('Get a token first'<\/span>);\n  axios.get('\/api\/posts'<\/span>, { headers: { Authorization: `Bearer ${token}` }})\n    .then(res => document.getElementById('out'<\/span>).textContent = JSON.stringify(res.data, null<\/span>, 2<\/span>))\n    .catch<\/span>(err => document.getElementById('out'<\/span>).textContent = err.response ? JSON.stringify(err.response.data, null<\/span>, 2<\/span>) : err);\n}\n<\/script>\n@endsection<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
The page first hits your password-grant proxy to fetch an access token (optionally with scopes), then uses it to call a scoped, protected API. This is perfect for quick verification without Postman.<\/p>\n\n\n\n\n
<\/div>\n\n\n\n\n
Wrapping Up<\/h2>\n\n\n\n
Passport equips Laravel with a full OAuth2 server: password and client-credentials grants, refresh tokens, personal access tokens, and scope-based authorization. You set up guard integration, issued tokens securely, enforced scopes on routes, and built a tiny UI to test flows. Choose Passport when you need interoperable OAuth2 with multiple client types and granular permissions; for simpler first-party apps, Sanctum may suffice.<\/p>\n\n\n\n\n
<\/div>\n\n\n\n\n
What\u2019s Next<\/h2>\n\n\n\n