Laravel Passport

https://github.com/laravel/passport
Admin
Laravel Passport is an OAuth2 server and API authentication package that provides simple and...
Tokens:103,722
Snippets:797
Trust Score:9.7
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Usage examples for passport commands

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/api-reference/console-commands.md

Bash commands for common Passport tasks: installation, key generation, client creation (confidential and public device-flow), re-hashing secrets, and scheduled cleanup.

```bash
# One-shot setup (keys + config + migrations + personal-access client):
php artisan passport:install

# Generate fresh keys:
php artisan passport:keys --force --length=4096

# Create a confidential web client:
php artisan passport:client --name "My App" --redirect_uri=https://app.example.com/callback

# Create a public device-flow client:
php artisan passport:client --device --public

# Re-hash legacy plaintext secrets:
php artisan passport:hash --force

# Scheduled cleanup of revoked + expired tokens (11.5 days):
php artisan passport:purge --hours=276
```

--------------------------------

### POST /oauth/token (Client Usage Examples)

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/api-reference/controllers.md

Client-side usage examples for the OAuth token endpoint, demonstrating authorization-code, refresh-token, and device-code grants.

```APIDOC
## POST /oauth/token

### Description
Client-side usage examples for the OAuth token endpoint, demonstrating authorization-code, refresh-token, and device-code grants.

### Method
POST

### Endpoint
/oauth/token

### Parameters
#### Request Body (Authorization-code grant)
- grant_type (string) - Required - Must be 'authorization_code'
- client_id (string) - Required - The client ID
- client_secret (string) - Required - The client secret
- code (string) - Required - The authorization code
- redirect_uri (string) - Required - The redirect URI
- code_verifier (string) - Required - The PKCE verifier
- scope (string) - Optional - Requested scopes

#### Request Body (Refresh-token grant)
- grant_type (string) - Required - Must be 'refresh_token'
- refresh_token (string) - Required - The refresh token
- client_id (string) - Required - The client ID
- client_secret (string) - Required - The client secret

#### Request Body (Device-code grant)
- grant_type (string) - Required - Must be 'urn:ietf:params:oauth:grant-type:device_code'
- client_id (string) - Required - The client ID
- client_secret (string) - Required - The client secret
- device_code (string) - Required - The device code

### Request Example
```php
// Authorization-code grant (PKCE):
POST https://app.test/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id=<id>&client_secret=<secret>
&code=<code>&redirect_uri=https://app.example.com/callback
&code_verifier=<pkce-verifier>&scope=read write
```

```php
// Refresh-token grant:
POST /oauth/token
grant_type=refresh_token&refresh_token=<token>&client_id=<id>&client_secret=<secret>
```

```php
// Device-code polling:
POST /oauth/token
grant_type=urn:ietf:params:oauth:grant-type:device_code
&client_id=<id>&client_secret=<secret>&device_code=<code>
// 400 {"error":"authorization_pending"} until approved, then 400 {"error":"slow_down"}
// while polling too frequently; 200 {token_type, expires_in, access_token, refresh_token} after approval.
```

### Response
#### Success Response (200)
- token_type (string) - The token type
- expires_in (integer) - Token expiration time in seconds
- access_token (string) - The access token
- refresh_token (string) - The refresh token

#### Error Response (400)
- error (string) - Error code, e.g., 'authorization_pending' or 'slow_down'

### Response Example
```json
{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "...",
  "refresh_token": "..."
}
```
```

--------------------------------

### SimpleViewResponse usage example

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/api-reference/responses.md

Demonstrates configuring authorization views using named views, inline closures, or direct instantiation.

```php
use Laravel\Passport\Http\Responses\SimpleViewResponse;
use Laravel\Passport\Passport;

// Named view:
Passport::authorizationView('oauth.authorize');

// Inline closure — full control over the HTTP response:
Passport::deviceAuthorizationView(fn (array $params) => view('oauth.device_authorize', $params));

// Direct use (what the authorization controllers receive):
$response = new SimpleViewResponse('oauth.authorize');
$response->withParameters(['client' => $client, 'user' => $user]);
```

--------------------------------

### Usage example for tokenCan, tokens, and createToken

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/api-reference/has-api-tokens.md

Demonstrates checking token scopes, revoking a token, and creating a personal access token.

```php
use Illuminate\Support\Facades\Auth;

$user = Auth::guard('api')->user();     // implements OAuthenticatable

if ($user && $user->tokenCan('read')) {
    // ...
}

// Revoke a specific historical token (repository-free):
$token = $user->tokens()->where('revoked', false)->first();
$token?->revoke();

// Create a personal access token programmatically:
$result = $user->createToken('CI token', ['read', 'write']);
echo $result->accessToken;      // the plain JWT to show once
echo $result->accessTokenId;    // DB id
```

--------------------------------

### Token usage example

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/api-reference/models.md

Shows how to query a user's active token, check a scope, revoke it, and eager load relationships.

```php
use Laravel\Passport\Passport;

$token = Passport::token()->newQuery()
    ->where('user_id', $user->getAuthIdentifier())
    ->where('revoked', false)
    ->first();

if ($token) {
    echo $token->can('read');     // scope check against $token->scopes
    $token->revoke();             // soft-revoke the access token
}

// Relationship access (eager loading supported):
$tokens = $user->tokens()->with('client', 'refreshToken')->get();
```

--------------------------------

### Token endpoint response example

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/endpoints.md

Example JSON response from the token endpoint (POST /oauth/token) on success. Includes token_type, expires_in, access_token, and refresh_token fields.

```json
{"token_type": "Bearer", "expires_in": 31536000, "access_token": "<jwt>", "refresh_token": "<id>"}
```

--------------------------------

### POST /oauth/device/code - JSON Response Example

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/endpoints.md

Example JSON response returned by the POST /oauth/device/code endpoint when the device code grant is enabled. The response includes the device_code, user_code, interval, expires_in, verification_uri, and verification_uri_complete fields. The interval and verification_uri_complete values are derived from the DeviceCodeGrant configuration in makeDeviceCodeGrant().

```json
{
  "device_code": "<80-char id>",
  "user_code": "ABCD-EFGH",
  "interval": 5,
  "expires_in": 600,
  "verification_uri": "http://localhost/oauth/device",
  "verification_uri_complete": "http://localhost/oauth/device?user_code=ABCD-EFGH"
}
```

--------------------------------

### Device flow client side status examples

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/api-reference/responses.md

Shows the expected redirect URLs after approving or denying a device authorization request.

```text
# After approving in the browser (POST /oauth/device/authorize with auth_token):
GET /oauth/device?status=authorization-approved
#   -> browser sees the confirmation page; the CLI polls /oauth/token for the token.

# After denying (DELETE /oauth/device/authorize):
GET /oauth/device?status=authorization-denied
```

--------------------------------

### Approval result handling usage example

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/api-reference/responses.md

Illustrates resolving the approval and denial response contracts from the container.

```php
use Laravel\Passport\Contracts\ApprovedDeviceAuthorizationResponse;
use Laravel\Passport\Contracts\DeniedDeviceAuthorizationResponse;

// These are resolved from the container:
// Approved -> redirect to GET /oauth/device?status=authorization-approved
// Denied   -> redirect to GET /oauth/device?status=authorization-denied
```

--------------------------------

### PassportUserProvider usage example

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/api-reference/has-api-tokens.md

Shows how to instantiate PassportUserProvider with a provider created via Auth::createUserProvider('users') and the provider name 'users'. Demonstrates calling getProviderName() and retrieveById(), which delegates to the underlying provider.

```php
use Laravel\Passport\PassportUserProvider;
use Illuminate\Support\Facades\Auth;

$passportProvider = new PassportUserProvider(
    Auth::createUserProvider('users'), 'users'
);

echo $passportProvider->getProviderName();   // 'users'
echo $passportProvider->retrieveById(1);     // delegates to provider
```

--------------------------------

### Usage example for session traits

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/api-reference/traits.md

Shows a custom controller using RetrievesAuthRequestFromSession to approve authorization requests, with note about InvalidAuthTokenException.

```php
use Laravel\Passport\Http\Controllers\RetrievesAuthRequestFromSession;
use Illuminate\Http\Request;

class MyApproveController
{
    use RetrievesAuthRequestFromSession;

    public function approve(Request $request)
    {
        $authRequest = $this->getAuthRequestFromSession($request);
        // InvalidAuthTokenException when the one-time auth_token doesn't match —
        // catch it in your exception handler to bounce the user back to /oauth/authorize.
    }
}
```

--------------------------------

### InstallCommand signature and handle method

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/api-reference/console-commands.md

Defines the passport:install command signature with --force and --length options, and declares the handle method. The command runs passport:keys, publishes config and migrations, then interactively offers migrate and passport:client --personal.

```php
protected $signature = 'passport:install
                        {--force : Overwrite keys they already exist}
                        {--length=4096 : The length of the private key}';
public function handle(): void
```

--------------------------------

### Usage examples for Passport middleware

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/api-reference/middleware.md

Shows how to apply various Passport middleware to routes: CheckToken for requiring all scopes, CheckTokenForAnyScope for at least one scope, EnsureClientIsResourceOwner for resource-owner-only clients, and CreateFreshApiToken to refresh the cookie on page loads.

```php
use Laravel\Passport\Http\Middleware\CheckToken;
use Laravel\Passport\Http\Middleware\CheckTokenForAnyScope;
use Laravel\Passport\Http\Middleware\EnsureClientIsResourceOwner;
use Laravel\Passport\Http\Middleware\CreateFreshApiToken;
use Illuminate\Support\Facades\Route;

// Require all scopes:
Route::get('/profile', fn () => ...)->middleware(CheckToken::using('user', 'read'));

// Require at least one scope:
Route::get('/reports', fn () => ...)->middleware(CheckTokenForAnyScope::using('admin', 'analyst'));

// Resource-owner-only client (client_credentials):
Route::get('/system/status', fn () => ...)->middleware(EnsureClientIsResourceOwner::using('status'));

// Refresh the cookie on page loads:
Route::get('/dashboard', fn () => ...)->middleware(CreateFreshApiToken::using('web'));
```

--------------------------------

### AuthorizeToken usage example

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/api-reference/middleware.md

Example of using the AuthorizeToken attribute on a controller class and methods. Shows applying 'read' scope to the class, 'write' scope to the store method with only option, and 'admin'/'moderator' scopes with anyScope true to allow any of them.

```php
use Laravel\Passport\Attributes\AuthorizeToken;

#[AuthorizeToken('read')]
class PostsController
{
    #[AuthorizeToken('write', only: ['store', 'update', 'destroy'])]
    public function store(Request $request) { /* ... */ }

    // Scopes are ANDed unless anyScope is true:
    #[AuthorizeToken(['admin', 'moderator'], anyScope: true)]
    public function moderate() { /* ... */ }
}
```

--------------------------------

### ApiTokenCookieFactory usage example

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/api-reference/personal-access-tokens.md

Example of using the factory to create a cookie for a user. The CSRF token is taken from the session. The returned cookie is attached to a response. Note that RefreshTokenController and CreateFreshApiToken already perform this task.

```php
use Laravel\Passport\ApiTokenCookieFactory;

$cookie = app(ApiTokenCookieFactory::class)->make(
    $user->getAuthIdentifier(),
    $request->session()->token(),      // the session's CSRF token
);

return (new Response('ok'))->withCookie($cookie);
```

--------------------------------

### UriRule usage example

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/api-reference/rules.md

Usage example for UriRule: validates a single URI. The first dataset passes validation, the second fails because 'javascript:alert(1)' is not a valid URL.

```php
use Illuminate\Contracts\Validation\Factory;

$validator = app(Factory::class);

$validator->make(
    ['redirect' => 'https://app.example.com/callback'],
    ['redirect' => ['required', new UriRule]],
)->validate();   // passes

$validator->make(
    ['redirect' => 'javascript:alert(1)'],
    ['redirect' => ['required', new UriRule]],
)->fails();      // true — not a valid URL
```

--------------------------------

### Scope usage example

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/api-reference/scope.md

Shows how to define scopes with Passport::tokensCan(), create a Scope instance, access its properties, and serialize it to JSON. Also demonstrates Passport::scopes() and Passport::scopesFor() for bulk scope retrieval, noting that undefined IDs are filtered out.

```php
use Laravel\Passport\Passport;
use Laravel\Passport\Scope;

Passport::tokensCan(['read' => 'Read resources', 'write' => 'Write resources']);

$scope = new Scope('read', 'Read resources');
echo $scope->id;             // 'read'
echo $scope->toJson();       // {"id":"read","description":"Read resources"}

// Scopes are produced in bulk via:
Passport::scopes();          // Collection<int, Scope>
Passport::scopesFor(['read', 'missing']); // Scope[] (undefined IDs filtered out)
```

--------------------------------

### Error-handling example using withErrorHandling

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/api-reference/traits.md

Shows how to use withErrorHandling to wrap a callback that responds to an access token request, converting League failures into OAuthServerException.

```php
// Error-handling example (same pattern the controllers use):
$this->withErrorHandling(fn () => $this->server->respondToAccessTokenRequest($psrRequest, $psrResponse));
// League failures (invalid_client, unsupported_grant_type, ...) are rethrown as
// Laravel\Passport\Exceptions\OAuthServerException with the RFC 6749 error payload.
```

--------------------------------

### RedirectRule usage example

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/api-reference/rules.md

Usage example for RedirectRule: validates a comma-separated list of redirect URIs. The first passes returns true, the second false, and message() returns the generic error message.

```php
use Laravel\Passport\Http\Rules\RedirectRule;
use Illuminate\Contracts\Validation\Factory;

$validator = app(Factory::class);
$rule = new RedirectRule($validator);

$rule->passes('redirect', 'https://a.example.com,https://b.example.com'); // true
$rule->passes('redirect', 'https://ok.example.com,not-a-url');            // false
$rule->message();   // 'One or more redirects have an invalid URI format.'
```

--------------------------------

### Authorization-code grant (PKCE) request

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/api-reference/controllers.md

Client-side example for the authorization-code grant with PKCE. It shows the POST request to /oauth/token with the required parameters including grant_type, client_id, client_secret, code, redirect_uri, code_verifier, and scope.

```php
// Authorization-code grant (PKCE):
POST https://app.test/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id=<id>&client_secret=<secret>
&code=<code>&redirect_uri=https://app.example.com/callback
&code_verifier=<pkce-verifier>&scope=read write
```

--------------------------------

### ResolvesInheritedScopes usage example

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/api-reference/scope.md

Demonstrates enabling inherited scopes and checking a token's permission with an ancestor prefix. Requires Passport::$withInheritedScopes to be true; the token must be created with a valid client_id.

```php
use Laravel\Passport\Passport;
use Laravel\Passport\Token;

Passport::$withInheritedScopes = true;

$token = Passport::token()->forceCreate([
    'id' => 'tok_1', 'user_id' => 1, 'client_id' => $client->getKey(),
    'scopes' => ['team:read'], 'revoked' => false,
]);

$token->can('team:read:reports'); // true — 'team:read' is an ancestor prefix
```

--------------------------------

### Create Passport clients with ClientFactory

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/api-reference/client.md

Use the ClientFactory to create a client with client credentials or personal access token grant types. The example shows creating a client with asClientCredentials() and asPersonalAccessTokenClient() with an owner.

```php
use Laravel\Passport\Database\Factories\ClientFactory;

$client = ClientFactory::new()->asClientCredentials()->create();
$client = ClientFactory::new()->asPersonalAccessTokenClient()->for($user, 'owner')->create();
```

--------------------------------

### Usage example: listening to Passport events

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/types.md

Shows how to register listeners for AccessTokenCreated, AccessTokenRevoked, and RefreshTokenCreated using the Event facade. The userId on AccessTokenCreated is null for client-credentials and personal-access-grant tokens issued without a user.

```php
use Illuminate\Support\Facades\Event;
use Laravel\Passport\Events\AccessTokenCreated;
use Laravel\Passport\Events\AccessTokenRevoked;
use Laravel\Passport\Events\RefreshTokenCreated;

Event::listen(AccessTokenCreated::class, function (AccessTokenCreated $event): void {
    log("issued token {$event->tokenId} (user {$event->userId}) for client {$event->clientId}");
});

Event::listen(AccessTokenRevoked::class, function (AccessTokenRevoked $event): void {
    log("revoked token {$event->tokenId}");
});

Event::listen(RefreshTokenCreated::class, function (RefreshTokenCreated $event): void {
    log("refresh {$event->refreshTokenId} -> access {$event->accessTokenId}");
});
```

--------------------------------

### Custom passport configuration and route prefix

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/api-reference/service-provider.md

Example configuration for config/passport.php and setting the route prefix via app config. The route prefix is read at boot from config('passport.path', 'oauth').

```php
// config/passport.php
return [
    'guard' => 'web',
    'middleware' => ['maintenance'],
    'private_key' => env('PASSPORT_PRIVATE_KEY'),
    'public_key'  => env('PASSPORT_PUBLIC_KEY'),
    'connection'  => env('PASSPORT_CONNECTION'),
];

// Route prefix is read at boot: config('passport.path', 'oauth')
// Set via app config:
'passport' => ['path' => 'oauth'],
```

--------------------------------

### Refresh-token grant request

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/api-reference/controllers.md

Client-side example for the refresh-token grant. It shows the POST request to /oauth/token with grant_type, refresh_token, client_id, and client_secret parameters.

```php
// Refresh-token grant:
POST /oauth/token
grant_type=refresh_token&refresh_token=<token>&client_id=<id>&client_secret=<secret>
```

--------------------------------

### GET /oauth/device

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/api-reference/controllers.md

Handles device user code entry. Without a user_code query parameter, it renders the user-code entry view. With a user_code query parameter, it redirects to the device authorization authorize route.

```APIDOC
## GET /oauth/device

### Description
Handles device user code entry. Without a user_code query parameter, it renders the user-code entry view. With a user_code query parameter, it redirects to the device authorization authorize route.

### Method
GET

### Endpoint
/oauth/device

### Parameters
#### Query Parameters
- **user_code** (string) - Optional - The user code entered by the user. If present, redirects to the device authorization authorize route.

### Response
#### Success Response (200)
Renders the user-code entry view when no `user_code` query parameter is provided.

#### Success Response (302)
Redirects to `passport.device.authorizations.authorize` with the `user_code` query parameter when provided.
```

--------------------------------

### Usage example for PersonalAccessTokenResult

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/api-reference/personal-access-tokens.md

Shows how to instantiate the class with OAuth response attributes and access them via camelCase properties. Note that 'tokenModel' is accessed via magic __get with the 'token' alias, and toArray() returns the camelized attribute map.

```php
use Laravel\Passport\PersonalAccessTokenResult;

$result = new PersonalAccessTokenResult([
    'access_token' => 'eyJ...', 'token_type' => 'Bearer',
    'expires_in' => 31536000, 'access_token_id' => 'tok123',
]);

echo $result->accessToken;         // 'eyJ...'
echo $result->tokenModel;          // Token model (via magic __get with 'token' alias)
echo $result->toArray();           // ['accessToken' => ..., 'tokenType' => ..., ...]
```

--------------------------------

### Instantiate and use Bridge\AccessToken, Client, Scope

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/api-reference/bridge-entities.md

Shows how to manually instantiate Laravel\Passport\Bridge entities (Client, Scope, AccessToken) and call methods inherited from EntityTrait and Bridge\Client. Use this to understand or test the bridge entity API outside of the typical repository flow. The example creates a confidential client, adds a 'read' scope, then constructs an access token for the authenticated user and echoes its identifier, client identifier, and grant type support.

```php
use Laravel\Passport\Bridge\AccessToken;
use Laravel\Passport\Bridge\Client;
use Laravel\Passport\Bridge\Scope;

$client = new Client('client-123', 'My App', ['https://app.example.com/cb'], isConfidential: true);
$scope  = new Scope('read');

$token = new AccessToken($user->getAuthIdentifier(), [$scope], $client);

echo $token->getIdentifier();        // from EntityTrait
echo $token->getClient()->getIdentifier();   // 'client-123'
echo $token->supportsGrantType('authorization_code'); // Bridge\Client::supportsGrantType
```

--------------------------------

### Using Passport::actingAs and Passport::actingAsClient

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/api-reference/passport.md

Shows how to use both helpers in a console script or test bootstrap. actingAs creates a synthetic access token for a user, while actingAsClient mocks the resource server to impersonate a client.

```php
use Laravel\Passport\Passport;

// In a console script or test bootstrap:
Passport::actingAs($user, ['user'], 'web');
Passport::actingAsClient($client, ['read'], 'api');
```

--------------------------------

### GET /oauth/scopes

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/api-reference/json-api-controllers.md

Returns all defined scopes as a collection of objects with id and description.

```APIDOC
## GET /oauth/scopes

### Description
Returns all defined scopes as a collection of objects with id and description.

### Method
GET

### Endpoint
/oauth/scopes

### Response
#### Success Response (200)
- **Collection<int, Scope>** - All defined scopes.

#### Response Example
[{"id":"read","description":"Read access"},{"id":"write","description":"Write access"}]
```

--------------------------------

### GET /oauth/clients

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/api-reference/json-api-controllers.md

Returns the user's clients as a JSON collection, with the secret hidden.

```APIDOC
## GET /oauth/clients

### Description
Returns the user's clients as a JSON collection, with the secret hidden.

### Method
GET

### Endpoint
/oauth/clients

### Response
#### Success Response (200)
- **Collection<int, Client>** - The user's clients.

#### Response Example
[{"id":1,"name":"Client Name","redirect":"http://example.com/callback","personal_access_client":false,"password_client":false,"revoked":false}]
```

--------------------------------

### Create a client with Passport

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/api-reference/client.md

Shows how to create a client using the Passport client model and forceCreate. The plain secret is available via plainSecret during creation, and methods like hasGrantType and confidential can be used to inspect the client.

```php
use Laravel\Passport\Passport;

$client = Passport::client()->forceCreate([
    'name' => 'My App',
    'secret' => $secret = Str::random(40),
    'redirect_uris' => ['https://app.example.com/callback'],
    'grant_types' => ['authorization_code', 'refresh_token'],
    'revoked' => false,
]);

echo $client->plainSecret;      // plain text available during creation
echo $client->hasGrantType('authorization_code'); // true
echo $client->confidential();   // true
```

--------------------------------

### GET /oauth/personal-access-tokens

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/api-reference/json-api-controllers.md

Returns the user's tokens filtered to non-revoked clients with grant type personal_access.

```APIDOC
## GET /oauth/personal-access-tokens

### Description
Returns the user's tokens filtered to non-revoked clients with grant type personal_access.

### Method
GET

### Endpoint
/oauth/personal-access-tokens

### Response
#### Success Response (200)
- **JSON array** - The user's personal access tokens.

#### Response Example
[{"id":1,"name":"token name","scopes":["read"],"revoked":false,"expires_at":"2025-01-01 00:00:00"}]
```

--------------------------------

### GET /oauth/tokens

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/api-reference/json-api-controllers.md

Returns the user's non-expired, non-revoked tokens, excluding revoked-client and first-party tokens.

```APIDOC
## GET /oauth/tokens

### Description
Returns the user's non-expired, non-revoked tokens, excluding revoked-client and first-party tokens.

### Method
GET

### Endpoint
/oauth/tokens

### Response
#### Success Response (200)
- **Collection<int, Token>** - The user's tokens.

#### Response Example
[{"id":1,"name":"token name","scopes":[],"revoked":false,"expires_at":"2025-01-01 00:00:00"}]
```

--------------------------------

### Construct TokenGuard with dependencies

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/api-reference/service-provider.md

Creates a new TokenGuard instance with the resource server, user provider, client repository, encrypter, and request. Used by the 'passport' guard.

```php
new TokenGuard(
    $this->app->make(ResourceServer::class),
    new PassportUserProvider(Auth::createUserProvider($config['provider']), $config['provider']),
    $this->app->make(ClientRepository::class),
    $this->app->make('encrypter'),
    $this->app->make('request')
)
```

--------------------------------

### Create personal access token with PersonalAccessTokenFactory::make

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/api-reference/personal-access-tokens.md

Resolves PersonalAccessTokenFactory from the container and calls make() to issue a personal access token. The provider must have a personal-access client; otherwise a RuntimeException is thrown.

```php
use Laravel\Passport\PersonalAccessTokenFactory;

$result = app(PersonalAccessTokenFactory::class)->make(
    $user->getAuthIdentifier(), 'deploy-token', ['read'], 'users'
);

echo $result->accessToken;   // opaque string to hand to the user
```

--------------------------------

### Handle personal access client not found error

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/api-reference/client-repository.md

Demonstrates catching the RuntimeException thrown by personalAccessClient() when no matching client exists. The error message and the artisan command to create one are shown in the comment.

```php
try {
    $client = $clients->personalAccessClient('users');
} catch (RuntimeException $e) {
    // "Personal access client not found for 'users' user provider. Please create one."
    // Trigger: run `php artisan passport:client --personal` to create one.
}
```

--------------------------------

### SimpleViewResponse constructor

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/api-reference/responses.md

Initializes the response with a view name or a closure.

```php
public function __construct(
    protected Closure|string $view,   // (\Closure(array<string, mixed>): (\Symfony\Component\HttpFoundation\Response))|string
)
```

--------------------------------

### DenyDeviceAuthorizationController constructor and __invoke

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/api-reference/controllers.md

Constructor and __invoke method for the DenyDeviceAuthorizationController. The __invoke method returns a DeniedDeviceAuthorizationResponse and behaves like the approve flow but with userApproved set to false, redirecting to the passport.device route with status=authorization-denied.

```php
public function __construct(
    protected AuthorizationServer $server,
)

public function __invoke(Request $request, DeniedDeviceAuthorizationResponse $response): DeniedDeviceAuthorizationResponse
```

--------------------------------

### GET /oauth/authorize

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/endpoints.md

Initiates the OAuth authorization flow. Validates the request, authenticates the user, and either redirects to the client with an authorization code or token, or prompts for consent.

```APIDOC
## GET /oauth/authorize

### Description
Initiates the OAuth authorization flow. Validates the request, authenticates the user, and either redirects to the client with an authorization code or token, or prompts for consent.

### Method
GET

### Endpoint
/oauth/authorize

### Parameters
#### Query Parameters
- **response_type** (string) - Required - `code` (authorization code) or `token` (implicit, only when enabled)
- **client_id** (string) - Required - Registered client
- **redirect_uri** (string) - Optional - Must match the client's registered URIs
- **scope** (string, space-separated) - Optional - Requested scopes
- **state** (string) - Optional - Opaque CSRF state, echoed back
- **prompt** (string) - Optional - Space-separated: `none`, `login`, `consent`
- **code_challenge** (string) - Optional - PKCE challenge
- **code_challenge_method** (string) - Optional - PKCE method (`S256`/`plain`)

### Response
#### Success Response (302)
- Redirect to `redirect_uri` with `code` (+ `state`), or `token` fragment for implicit

#### Success Response (200)
- Render of `AuthorizationViewResponse` with parameters `client`, `user`, `scopes`, `request`, `authToken`; session gains `authToken` + serialized `authRequest`

#### Error Responses
- `prompt=none`, unauthenticated: redirect error `login_required` (401)
- `prompt=none`, consent still required: redirect error `consent_required` (401)
- `prompt=login`, no `promptedForLogin` session flag: logout, session regenerate, redirect to login (`AuthenticationException`)
- Failed validation: 400 redirect/body OAuth error per `OAuthServerException` (fragment-encoded for implicit)
```

--------------------------------

### GET /oauth/device/authorize

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/api-reference/controllers.md

Displays the device authorization approval view. Validates the user code, attaches the authenticated user to the device code, and renders the approval screen.

```APIDOC
## GET /oauth/device/authorize

### Description
Displays the device authorization approval view. Validates the user code, attaches the authenticated user to the device code, and renders the approval screen.

### Method
GET

### Endpoint
/oauth/device/authorize

### Parameters
#### Query Parameters
- **user_code** (string) - Required - The user code provided by the device.

### Response
#### Success Response (200)
Renders the approval view with client, user, scopes, request, and authToken.

#### Redirects
- Missing user_code → redirect to route `passport.device`.
- Code not found/expired/claimed → redirect back with input and error `user_code: 'Incorrect code.'`.
```

--------------------------------

### ClientController constructor

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/api-reference/json-api-controllers.md

Constructor for ClientController with ClientRepository, ValidationFactory, and RedirectRule dependencies.

```php
public function __construct(
    protected ClientRepository $clients,
    protected ValidationFactory $validation,
    protected RedirectRule $redirectRule,
)
```

--------------------------------

### Configure Passport options in config/passport.php

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/configuration.md

Full configuration array for config/passport.php. Sets the guard for authorize/approve routes, extra middleware, private/public keys from environment variables, and an optional database connection.

```php
// config/passport.php — full application of every option
return [
    'guard'          => 'web',                       // authorize/approve routes authenticate via this guard
    'middleware'     => ['maintenance'],             // extra middleware on all Passport routes
    'private_key'    => env('PASSPORT_PRIVATE_KEY'), // or publish keys as files
    'public_key'     => env('PASSPORT_PUBLIC_KEY'),
    'connection'     => env('PASSPORT_CONNECTION'),  // e.g. 'oauth' database connection
];
```

--------------------------------

### DeniedDeviceAuthorizationResponse toResponse method

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/api-reference/responses.md

Redirects the user to the device route with a denial status.

```php
public function toResponse($request)
{
    return to_route('passport.device')
        ->with('status', 'authorization-denied');
}
```

--------------------------------

### Catching OAuthServerException

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/errors.md

Example of catching OAuthServerException in a custom exception handler. The getResponse() method returns a Symfony Response that already contains the RFC 6749 error body or redirect with error parameters.

```php
use Laravel\Passport\Exceptions\OAuthServerException;

catch (OAuthServerException $e) {
    $response = $e->getResponse();           // Symfony\Component\HttpFoundation\Response
    // already carries RFC 6749 error body / redirect with error params
}
```

--------------------------------

### Create and regenerate an authorization code grant client

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/api-reference/client-repository.md

Shows how to resolve the ClientRepository singleton from the container, create an authorization code grant client with a redirect URI and user, then regenerate its secret. The plain secret is echoed once immediately after creation.

```php
use Laravel\Passport\ClientRepository;

$clients = app(ClientRepository::class);   // singleton

$client = $clients->createAuthorizationCodeGrantClient(
    'My Web App',
    ['https://app.example.com/callback'],
    confidential: true,
    user: $user,
);

$clients->regenerateSecret($client);
echo $client->plainSecret;   // shown once, immediately after creation
```

--------------------------------

### ApprovedDeviceAuthorizationResponse toResponse method

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/api-reference/responses.md

Redirects the user to the device route with an approval status.

```php
public function toResponse($request)
{
    return to_route('passport.device')
        ->with('status', 'authorization-approved');
}
```

--------------------------------

### cookie(?string $cookie = null): string

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/api-reference/passport.md

Gets or sets the API token cookie name. If `$cookie` is `null`, reads the current value; otherwise sets the cookie name. Default is `'laravel_token'`.

```APIDOC
## cookie(?string $cookie = null): string

### Description
Gets or sets the API token cookie name. If `$cookie` is `null`, reads the current value; otherwise sets the cookie name. Default is `'laravel_token'`.

### Method
Get/set (static)

### Signature
`cookie(?string $cookie = null): string`

### Parameters
- **$cookie** (?string) - Optional - When provided, sets the cookie name; when `null`, reads the current value.

### Return Value
Returns the current API token cookie name as a string.

### Example
```php
Passport::cookie('my_app_token'); // rename the API cookie
```
```

--------------------------------

### ApprovedDeviceAuthorizationResponse::toResponse

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/api-reference/responses.md

Returns a redirect to the device entry route with a status parameter indicating approval.

```APIDOC
## ApprovedDeviceAuthorizationResponse::toResponse

### Description
Returns a redirect to the device entry route (`GET /oauth/device`) with a `status = authorization-approved` query parameter.

### Method
toResponse

### Signature
`toResponse($request)`

### Parameters
- **$request** (Illuminate\Http\Request) - Required - The incoming request.

### Returns
- RedirectResponse - A redirect to `GET /oauth/device?status=authorization-approved`.

### Example
```php
// After approving in the browser (POST /oauth/device/authorize with auth_token):
GET /oauth/device?status=authorization-approved
```
```

--------------------------------

### personalAccessTokensExpireIn(DateTimeInterface|DateInterval|null $date = null): DateInterval

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/api-reference/passport.md

Gets or sets the personal-access-token lifetime. Passing a `DateInterval` or `DateTimeInterface` sets the lifetime; passing `null` or omitting reads the current value. Default is `new DateInterval('P1Y')`.

```APIDOC
## personalAccessTokensExpireIn(DateTimeInterface|DateInterval|null $date = null): DateInterval

### Description
Gets or sets the personal-access-token lifetime. Passing a `DateInterval` or `DateTimeInterface` sets the lifetime; passing `null` or omitting reads the current value. Default is `new DateInterval('P1Y')`.

### Method
Get/set (static)

### Signature
`personalAccessTokensExpireIn(DateTimeInterface|DateInterval|null $date = null): DateInterval`

### Parameters
- **$date** (DateTimeInterface|DateInterval|null) - Optional - When provided, sets the token lifetime; when `null` or omitted, reads the current value.

### Return Value
Returns the current personal-access-token lifetime as a `DateInterval` object.

### Example
```php
Passport::personalAccessTokensExpireIn(new DateInterval('P90D')); // set
```
```

--------------------------------

### Migration to apply new oauth_clients schema

Source: https://github.com/laravel/passport/blob/13.x/UPGRADE.md

Creates a migration to apply the new oauth_clients table structure. It adds owner_type/owner_id, redirect_uris, and grant_types columns, migrates existing data, then drops old columns. Recommended for integer-based client IDs to avoid 401 errors.

```php
Schema::table('oauth_clients', function (Blueprint $table) {
    $table->nullableMorphs('owner', after: 'user_id');

    $table->after('provider', function (Blueprint $table) {
        $table->text('redirect_uris')->nullable();
        $table->text('grant_types')->nullable();
    });
});

foreach (Passport::client()->cursor() as $client) {
    Model::withoutTimestamps(fn () => $client->forceFill([
        'owner_id' => $client->user_id,
        'owner_type' => $client->user_id
            ? config('auth.providers.'.($client->provider ?: config('auth.guards.api.provider')).'.model')
            : null,
        'redirect_uris' => $client->redirect_uris,
        'grant_types' => $client->grant_types,
    ])->save());
}

Schema::table('oauth_clients', function (Blueprint $table) {
    $table->dropColumn(['user_id', 'redirect', 'personal_access_client', 'password_client']);

    $table->text('redirect_uris')->nullable(false)->change();
    $table->text('grant_types')->nullable(false)->change();
});
```

--------------------------------

### refreshTokensExpireIn(DateTimeInterface|DateInterval|null $date = null): DateInterval

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/api-reference/passport.md

Gets or sets the refresh-token lifetime. Passing a `DateInterval` or `DateTimeInterface` sets the lifetime; passing `null` or omitting reads the current value. Default is `new DateInterval('P1Y')`.

```APIDOC
## refreshTokensExpireIn(DateTimeInterface|DateInterval|null $date = null): DateInterval

### Description
Gets or sets the refresh-token lifetime. Passing a `DateInterval` or `DateTimeInterface` sets the lifetime; passing `null` or omitting reads the current value. Default is `new DateInterval('P1Y')`.

### Method
Get/set (static)

### Signature
`refreshTokensExpireIn(DateTimeInterface|DateInterval|null $date = null): DateInterval`

### Parameters
- **$date** (DateTimeInterface|DateInterval|null) - Optional - When provided, sets the token lifetime; when `null` or omitted, reads the current value.

### Return Value
Returns the current refresh-token lifetime as a `DateInterval` object.

### Example
```php
Passport::refreshTokensExpireIn(new DateInterval('P1M')); // set
```
```

--------------------------------

### Register Passport views with viewNamespace and deviceUserCodeView

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/api-reference/passport.md

Shows how to register Passport's conventional views using viewNamespace, and how to override the device user-code view with a closure for full control. The closure receives an array of parameters and returns a response.

```php
use Laravel\Passport\Passport;

Passport::viewNamespace('passport');     // passport.authorize, passport.device.authorize, passport.device.user-code
// or a closure for full control:
Passport::deviceUserCodeView(fn (array $params) => response()->view('oauth.device-user-code', $params));
```

--------------------------------

### DeniedDeviceAuthorizationResponse::toResponse

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/api-reference/responses.md

Returns a redirect to the device entry route with a status parameter indicating denial.

```APIDOC
## DeniedDeviceAuthorizationResponse::toResponse

### Description
Returns a redirect to the device entry route (`GET /oauth/device`) with a `status = authorization-denied` query parameter.

### Method
toResponse

### Signature
`toResponse($request)`

### Parameters
- **$request** (Illuminate\Http\Request) - Required - The incoming request.

### Returns
- RedirectResponse - A redirect to `GET /oauth/device?status=authorization-denied`.

### Example
```php
// After denying (DELETE /oauth/device/authorize):
GET /oauth/device?status=authorization-denied
```
```

--------------------------------

### defaultScopes(array|string|null $scopes = null): array

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/api-reference/passport.md

Get or set the default scopes. Passing `null` (or omitting) returns the current default scopes as `string[]`. Passing `array|string` sets the default scope and returns the resulting `string[]`.

```APIDOC
## `defaultScopes(array|string|null $scopes = null): array`

### Description
Get or set the default scopes. Passing `null` (or omitting) returns the current default scopes as `string[]` (`explode(' ', static::$defaultScope)`, or `[]` when empty). Passing `array|string` sets `static::$defaultScope` (arrays are `implode(' ', ...)`d) and returns the resulting `string[]`.

### Method
`defaultScopes`

### Signature
`Passport::defaultScopes(array|string|null $scopes = null): array`

### Parameters
- **$scopes** (array|string|null) - Optional - Scope ID(s); omit to read. Default: `null`

### Return Value
`string[]` — currently configured default scope IDs.

```

--------------------------------

### Hash existing client secrets with Artisan command

Source: https://github.com/laravel/passport/blob/13.x/UPGRADE.md

Run the passport:hash Artisan command to hash all existing client secrets stored in plain text.

```bash
php artisan passport:hash
```

--------------------------------

### Set personal access client credentials in .env

Source: https://github.com/laravel/passport/blob/13.x/UPGRADE.md

Before hashing client secrets, set the personal access client ID and unhashed secret in your .env file. This is required to avoid irreversible data loss.

```env
PASSPORT_PERSONAL_ACCESS_CLIENT_ID=client-id-value
PASSPORT_PERSONAL_ACCESS_CLIENT_SECRET=unhashed-client-secret-value
```

--------------------------------

### clientCredentialsTokensExpireIn(DateTimeInterface|DateInterval|null $date = null): DateInterval

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/api-reference/passport.md

Gets or sets the client-credentials token lifetime. Passing a `DateInterval` or `DateTimeInterface` sets the lifetime; passing `null` or omitting reads the current value. Default falls back to `static::tokensExpireIn()`.

```APIDOC
## clientCredentialsTokensExpireIn(DateTimeInterface|DateInterval|null $date = null): DateInterval

### Description
Gets or sets the client-credentials token lifetime. Passing a `DateInterval` or `DateTimeInterface` sets the lifetime; passing `null` or omitting reads the current value. Default falls back to `static::tokensExpireIn()`.

### Method
Get/set (static)

### Signature
`clientCredentialsTokensExpireIn(DateTimeInterface|DateInterval|null $date = null): DateInterval`

### Parameters
- **$date** (DateTimeInterface|DateInterval|null) - Optional - When provided, sets the token lifetime; when `null` or omitted, reads the current value.

### Return Value
Returns the current client-credentials token lifetime as a `DateInterval` object.

### Example
```php
Passport::clientCredentialsTokensExpireIn(new DateInterval('P1M')); // set
```
```

--------------------------------

### tokensExpireIn(DateTimeInterface|DateInterval|null $date = null): DateInterval

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/api-reference/passport.md

Gets or sets the access-token lifetime. Passing a `DateInterval` or `DateTimeInterface` sets the lifetime; passing `null` or omitting reads the current value. Default is `new DateInterval('P1Y')` (1 year).

```APIDOC
## tokensExpireIn(DateTimeInterface|DateInterval|null $date = null): DateInterval

### Description
Gets or sets the access-token lifetime. Passing a `DateInterval` or `DateTimeInterface` sets the lifetime; passing `null` or omitting reads the current value. Default is `new DateInterval('P1Y')` (1 year).

### Method
Get/set (static)

### Signature
`tokensExpireIn(DateTimeInterface|DateInterval|null $date = null): DateInterval`

### Parameters
- **$date** (DateTimeInterface|DateInterval|null) - Optional - When provided, sets the token lifetime; when `null` or omitted, reads the current value.

### Return Value
Returns the current access-token lifetime as a `DateInterval` object.

### Example
```php
Passport::tokensExpireIn(new DateInterval('P2W')); // set
$ttl = Passport::tokensExpireIn(); // read, returns DateInterval("P2W")
```
```

--------------------------------

### Using TransientToken to check scopes

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/api-reference/access-token.md

Creates a new TransientToken instance and demonstrates that it grants all scopes and is transient. Cookie-authenticated users have all scopes, and the token is not persisted.

```php
use Laravel\Passport\Contracts\ScopeAuthorizable;
use Laravel\Passport\TransientToken;

$token: ScopeAuthorizable = new TransientToken;
echo $token->can('anything');        // true — cookie-authenticated users have all scopes
echo $token->transient();            // true — not persisted, no DB row
```

--------------------------------

### ApproveDeviceAuthorizationController constructor and __invoke

Source: https://github.com/laravel/passport/blob/13.x/_autodocs/api-reference/controllers.md

Constructor and __invoke signature for the device authorization approval endpoint. Injects AuthorizationServer; __invoke completes authorization with userApproved = true and returns the response contract. Throws InvalidAuthTokenException on session token mismatch.

```php
public function __construct(
    protected AuthorizationServer $server,
)

public function __invoke(Request $request, ApprovedDeviceAuthorizationResponse $response): ApprovedDeviceAuthorizationResponse
```
Tokens:
Raw