devnotes: Skill for Claude Code

Passport OAuth2 Authentication

Documentation First

Always use search-docs before writing Passport code. The documentation covers every grant type, configuration option, and edge case in detail. This skill teaches you how to navigate Passport — the docs have the implementation specifics.

search-docs(queries: ["Passport installation"], packages: ["laravel/[email protected]"])

The Passport docs live under the laravel/framework package — not laravel/passport.

When to Apply

Activate this skill when:

• Installing or configuring Passport
• Setting up OAuth2 authorization grants
• Creating or managing OAuth clients
• Protecting API routes with token authentication
• Defining or checking token scopes
• Configuring SPA cookie-based authentication
• Choosing between Passport and Sanctum

Passport vs. Sanctum

Passport is a full OAuth2 server — use it when third-party applications need to consume your API and when you need OAuth2 authorization code grants, client credentials for machine-to-machine auth, or device authorization flow.

Sanctum is simpler — use it when first-party SPAs, third parties, or mobile apps consume the API but you don't need the full OAuth2 grant flows.

Installation

Three steps are always required:

1. Install Passport

php artisan install:api --passport

This publishes migrations, generates encryption keys, and registers routes.

2. Configure the User model

The User model needs both the HasApiTokens trait AND the OAuthenticatable interface. Missing the interface is the most common Passport setup mistake — it causes runtime errors that can be confusing to debug.

use Laravel\Passport\Contracts\OAuthenticatable;
use Laravel\Passport\HasApiTokens;

class User extends Authenticatable implements OAuthenticatable
{
    use HasApiTokens;
}

3. Configure the auth guard

The api guard must use the passport driver in config/auth.php. Using token or sanctum here silently breaks Passport authentication.