Laravel Sanctum

https://github.com/laravel/sanctum
Admin
Laravel Sanctum provides a featherweight authentication system for SPAs and simple APIs, offering...
Tokens:33,279
Snippets:281
Trust Score:9.7
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### createToken() usage example

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

Example of creating a token with specific abilities and an expiration date, then returning the plain-text token and token ID in a JSON response.

```php
$token = $user->createToken('mobile-app', ['tickets:read', 'tickets:create'], now()->addDays(7));

return response()->json([
    'token' => $token->plainTextToken, // "1|abc...zXY"
    'token_id' => $token->accessToken->id,
]);
```

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

### Example: mapping AuthenticationException to redirect

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/frontend-middleware.md

Example middleware that catches AuthenticationException and redirects to the login route. Use this to customize the response when the session is invalidated.

```php
use Illuminate\Auth\AuthenticationException;
use Illuminate\Http\Request;

public function handle(Request $request, \Closure $next)
{
    try {
        return $next($request);
    } catch (AuthenticationException $e) {
        return redirect()->guest(route('login'));
    }
}
```

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

### Basic creation and response example

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/new-access-token.md

Shows how to create a token with abilities and return the plain-text token to the client. The plain-text token is shown only once.

```php
$newToken = $user->createToken('web', ['tickets:read']);

// Return the plain-text token to the client (shown only once):
return response()->json([
    'token' => $newToken->plainTextToken,
    'token_type' => 'Bearer',
]);
```

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

### tokenCant() usage example

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

Example usage of tokenCan() and tokenCant() to check token abilities. tokenCant() is the logical negation of tokenCan().

```php
if ($user->tokenCan('tickets:create')) {
    // token grants the ability
}

if ($user->tokenCant('admin')) {
    abort(403, 'Admin ability required.');
}
```

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

### Resolving user with guard directly

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/guard.md

Example of using the guard directly to get the authenticated user, aborting with a 401 if null.

```php
$user = app('auth')->guard('sanctum')->user();

if (is_null($user)) {
    abort(401);
}
```

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

### Listening with a closure in boot()

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/events.md

Example of registering an event listener in a service provider's boot() method to log token usage.

```php
use Illuminate\Support\Facades\Event;
use Laravel\Sanctum\Events\TokenAuthenticated;

public function boot(): void
{
    Event::listen(function (TokenAuthenticated $event) {
        activity()
            ->performedOn($event->token->tokenable)
            ->log('Personal access token #'.$event->token->getKey().' used');
    });
}
```

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

### Revoke all tokens example

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

Shows how to delete all tokens for a user.

```php
$user->tokens()->delete(); // revoke all tokens
```

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

### Inspecting current token in a controller

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

Example controller method that uses currentAccessToken() to retrieve the token and return user, token name, and token ID.

```php
use Illuminate\Http\Request;

public function profile(Request $request)
{
    $token = $request->user()->currentAccessToken();

    return [
        'user' => $request->user(),
        'token_name' => $token?->name,
        'token_id' => $token?->getKey(),
    ];
}
```

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

### findToken() usage example

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/personal-access-token.md

Retrieves a token from the bearer token and accesses its tokenable model if found.

```php
$token = PersonalAccessToken::findToken($request->bearerToken());

if ($token) {
    $user = $token->tokenable;
}
```

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

### Sanctum::usePersonalAccessTokenModel() example

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/sanctum.md

Call from a service provider's boot() method to replace the token model with a custom one. The model must implement HasAbilities, typically extending PersonalAccessToken.

```php
use App\Models\Sanctum\PersonalAccessToken;
use Laravel\Sanctum\Sanctum;

public function boot(): void
{
    Sanctum::usePersonalAccessTokenModel(PersonalAccessToken::class);
}
```

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

### Catching MissingScopeException in legacy code

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/scope-middleware.md

Example of catching the legacy MissingScopeException to handle missing scopes. The scopes() method returns an array of required scopes that the token lacked.

```php
use Laravel\Sanctum\Exceptions\MissingScopeException;

try {
    // scoped route call
} catch (MissingScopeException $e) {
    // $e->scopes() — array of required scopes the token lacked
    abort(403, 'Missing scopes: '.implode(', ', $e->scopes()));
}
```

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

### JSON serialization variants example

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/new-access-token.md

Demonstrates toJson() with JSON_PRETTY_PRINT and toArray()/json_encode(). The model's 'token' attribute is hidden, so the hash is never serialized.

```php
$newToken = $user->createToken('cli');

echo $newToken->toJson(JSON_PRETTY_PRINT);

// Both serialize the model's "token" attribute away because it is $hidden,
// so the JSON output contains the model attributes but never the hash.
$array = $newToken->toArray();
$json = json_encode($newToken);
```

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

### Raw HTTP request with curl

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/csrf-cookie-controller.md

Sends a GET request to the CSRF cookie endpoint and shows the expected 204 response with the Set-Cookie header.

```bash
curl -i http://localhost/sanctum/csrf-cookie
# HTTP/1.1 204 No Content
# Set-Cookie: XSRF-TOKEN=...; ...
```

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

### Catching Sanctum exceptions in consumer code

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/exceptions.md

Example of catching MissingAbilityException and AuthorizationException in a try-catch block. The catch for AuthorizationException also catches MissingAbilityException and MissingScopeException because they extend it.

```php
use Illuminate\Auth\Access\AuthorizationException;
use Laravel\Sanctum\Exceptions\MissingAbilityException;

try {
    // guarded route call
} catch (MissingAbilityException $e) {
    abort(403, 'Missing: '.implode(', ', $e->abilities()));
} catch (AuthorizationException $e) {
    // also catches MissingAbilityException / MissingScopeException
    throw $e;
}
```

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

### Define CSRF cookie route

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

Registers the GET /sanctum/csrf-cookie route with the 'web' middleware and name 'sanctum.csrf-cookie'. This route is only registered if routes are not cached and config('sanctum.routes') is not false.

```php
Route::get('/csrf-cookie', CsrfCookieController::class.'@show')->middleware('web')->name('sanctum.csrf-cookie');
```

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

### Sanctum::getAccessTokenFromRequestUsing() example

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/sanctum.md

Override the default bearer token extraction by providing a callback that reads from a custom header. The callback receives the Request instance and must return a string.

```php
use Illuminate\Http\Request;
use Laravel\Sanctum\Sanctum;

Sanctum::getAccessTokenFromRequestUsing(function (Request $request) {
    return $request->header('X-API-Token', '');
});
```

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

### Sanctum::personalAccessTokenModel() - Retrieve Token Model Class

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/sanctum.md

Returns the class name of the currently registered token model. The example shows how to use the returned class name to find a token by its plain text token.

```php
$model = Sanctum::personalAccessTokenModel(); // e.g. "Laravel\Sanctum\PersonalAccessToken"

$token = $model::findToken($plainTextToken);
```

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

### Distinguishing request types with TransientToken

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/transient-token.md

Example of checking if the current access token is a TransientToken to differentiate stateful session requests from API requests with personal access tokens. Note that TransientToken does not have a 'name' attribute.

```php
use Laravel\Sanctum\TransientToken;

$token = $request->user()->currentAccessToken();

if ($token instanceof TransientToken) {
    // stateful, first-party session request
} else {
    // API request with a personal access token (or null)
}
```

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

### Listening with a dedicated listener class

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/events.md

Shows how to register a dedicated listener class and its implementation. The listener updates the user's last_token_used_at timestamp.

```php
// app/Providers/AppServiceProvider.php
Event::listen(TokenAuthenticated::class, TokenUsageListener::class);

// app/Listeners/TokenUsageListener.php
use Laravel\Sanctum\Events\TokenAuthenticated;

class TokenUsageListener
{
    public function handle(TokenAuthenticated $event): void
    {
        $user = $event->token->tokenable;
        $user->last_token_used_at = now();
        $user->save();
    }
}
```

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

### Sanctum::currentApplicationUrlWithPort() usage in config/sanctum.php

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/sanctum.md

Shows how to use Sanctum::currentApplicationUrlWithPort() in the default config/sanctum.php to build the 'stateful' domain list. It concatenates the returned host (with port) to the default localhost domains.

```php
'stateful' => explode(',', env('SANCTUM_STATEFUL_DOMAINS', sprintf(
    '%s%s',
    'localhost,localhost:3000,127.0.0.1,127.0.0.1:8000,::1',
    Sanctum::currentApplicationUrlWithPort(),
))),
```

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

### Laravel feature test for CSRF cookie endpoint

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/endpoints.md

Assert that the endpoint returns 204 and sets the cookie, using both getJson and get methods.

```php
// Laravel feature test: assert 204 and the cookie set
$this->getJson('/sanctum/csrf-cookie')->assertNoContent();
$this->get('/sanctum/csrf-cookie')->assertNoContent();
```

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

### AuthenticateSession handle method

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/frontend-middleware.md

Main middleware handler. Re-validates password hashes for stateful guards and throws AuthenticationException if invalid.

```php
public function handle(Request $request, Closure $next): Response
```

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

### Sanctum::currentApplicationUrlWithPort() method signature

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/sanctum.md

Declares the public static method currentApplicationUrlWithPort() that returns a string. It reads APP_URL via config('app.url') and parses it with parse_url, returning ',host', ',host:port', or '' when the config value is falsy.

```php
public static function currentApplicationUrlWithPort()
```

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

### createToken()

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

Creates a new personal access token record and returns the plain-text token exactly once. The token is hashed (SHA-256) before storage.

```APIDOC
## `createToken()`

### Description
Creates a new personal access token record and returns the plain-text token exactly once. Only the SHA-256 hash is persisted; the returned `id|plainText` string is the only chance to see the plain-text value.

### Method
`createToken`

### Parameters
- **$name** (string) - Required - Human-readable token name, stored in the `name` column.
- **$abilities** (array) - Optional - Default: `['*']` - Abilities granted to the token; `'*'` grants everything.
- **$expiresAt** (\DateTimeInterface|null) - Optional - Default: `null` - Optional expiry; stored in `expires_at` and enforced by `Guard::isValidAccessToken()`.

### Return Type
`\Laravel\Sanctum\NewAccessToken` - Wraps the persisted model plus the plain-text token.

### Example
```php
$token = $user->createToken('mobile-app', ['tickets:read', 'tickets:create'], now()->addDays(7));

return response()->json([
    'token' => $token->plainTextToken, // "1|abc...zXY"
    'token_id' => $token->accessToken->id,
]);
```
```

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

### Create RequestGuard instance

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

Constructs a RequestGuard wrapping a Guard with expiration, provider, and last_used_at settings. The guard authenticates against the current request.

```php
return new RequestGuard(
    new Guard(
        $auth,
        config('sanctum.expiration'),          // int|null
        $config['provider'],                    // string|null
        config('sanctum.last_used_at', true)    // bool
    ),
    request(),
    $auth->createUserProvider($config['provider'] ?? null)
);
```

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

### GET /sanctum/csrf-cookie

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/csrf-cookie-controller.md

Returns a 204 No Content response to trigger the browser to store the XSRF-TOKEN cookie. The cookie is attached by the web middleware group, not the controller itself.

```APIDOC
## [GET] /sanctum/csrf-cookie

### Description
Returns an empty 204 No Content response to trigger the browser to store the XSRF-TOKEN cookie for subsequent SPA requests. The cookie is attached by the web middleware group (EncryptCookies and StartSession) rather than by the controller itself.

### Method
GET

### Endpoint
/sanctum/csrf-cookie

### Parameters
No parameters.

### Request Example
No request body or query parameters.

### Response
#### Success Response (204 No Content)
- **Body**: empty
- **Cookies set by middleware**: `XSRF-TOKEN` (via `Illuminate\Cookie\Middleware\EncryptCookies`); session cookie (via `Illuminate\Session\Middleware\StartSession`, when sessions run on the route)

#### Response Example
```
HTTP/1.1 204 No Content
Set-Cookie: XSRF-TOKEN=...; ...
```

### Notes
- The route is named `sanctum.csrf-cookie` and is registered with the `web` middleware group.
- The route path is affected by configuration: `sanctum.prefix` (default `'sanctum'`) changes the path to `/{prefix}/csrf-cookie`; if `sanctum.routes` is set to `false` or routes are cached, the route is not registered.
- No authentication is required for this endpoint.
```

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

### createToken() internal implementation

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

Internal implementation of createToken(): generates a plain-text token, stores its SHA-256 hash, and returns a NewAccessToken instance containing the model and the plain-text token.

```php
$plainTextToken = $this->generateTokenString();

$token = $this->tokens()->create([
    'name' => $name,
    'token' => hash('sha256', $plainTextToken),
    'abilities' => $abilities,
    'expires_at' => $expiresAt,
]);

return new NewAccessToken($token, $token->getKey().'|'.$plainTextToken);
```

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

### Publish Sanctum migrations

Source: https://github.com/laravel/sanctum/blob/4.x/UPGRADE.md

Run this artisan command to publish Sanctum's migrations to your application, as they are no longer automatically loaded in version 4.0.

```bash
php artisan vendor:publish --tag=sanctum-migrations
```

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

### generateTokenString()

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

Builds a plain-text token string using a configurable prefix, 40 random characters, and a crc32b hash. Returns the generated token string.

```APIDOC
## generateTokenString()

### Description
Builds the plain-text token as `{config('sanctum.token_prefix', '')}{Str::random(40)}{hash('crc32b', $tokenEntropy)}`. The prefix comes from the `token_prefix` configuration option (env `SANCTUM_TOKEN_PREFIX`).

### Method
`generateTokenString()`

### Return Type
`string` — a ~45-character token string (prefix + 40 random characters + 8-char crc32b hex).

### Source
`src/HasApiTokens.php:79`
```

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

### Canonical User model using HasApiTokens

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

Shows the standard way to implement the HasApiTokens contract in a User model.

```php
use Illuminate\Foundation\Auth\User as Authenticatable;
use Laravel\Sanctum\Contracts\HasApiTokens as HasApiTokensContract;
use Laravel\Sanctum\HasApiTokens;

class User extends Authenticatable implements HasApiTokensContract
{
    use HasApiTokens;
}
```

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

### Sanctum::currentApplicationUrlWithPort()

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/sanctum.md

Returns the host (with port, if any) of the application URL, prefixed with a comma, for concatenation into the stateful domain list. Reads APP_URL via config('app.url') and parses it with parse_url.

```APIDOC
## Sanctum::currentApplicationUrlWithPort()

### Description
Returns the host (with port, if any) of the application URL, prefixed with a comma, for concatenation into the `stateful` domain list. Reads `APP_URL` via `config('app.url')` and parses it with `parse_url`.

### Method
Static method

### Signature
```php
public static function currentApplicationUrlWithPort()
```

### Parameters
None

### Return Value
- **Type:** `string`
- **Description:** `',host'`, `',host:port'`, or `''` when `config('app.url')` is falsy.

### Example
```php
'stateful' => explode(',', env('SANCTUM_STATEFUL_DOMAINS', sprintf(
    '%s%s',
    'localhost,localhost:3000,127.0.0.1,127.0.0.1:8000,::1',
    Sanctum::currentApplicationUrlWithPort(),
))),
```

### Source
`src/Sanctum.php:45`
```

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

### Sanctum::authenticateAccessTokensUsing() - Custom Token Validation

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/sanctum.md

Registers a callback that receives the access token instance and the boolean result of built-in validity checks. The callback must return a boolean. Use this to add extra validation, such as checking an attribute on the token row. The example requires an additional 'user_agent' attribute on the token.

```php
use Laravel\Sanctum\Sanctum;

Sanctum::authenticateAccessTokensUsing(function ($accessToken, bool $isValid) {
    return $isValid && $accessToken->user_agent === request()->userAgent();
});
```

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

### Laravel\Sanctum\Http\Middleware\CheckAbilities::handle

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/ability-middleware.md

Requires the token to have every listed ability. Throws MissingAbilityException for the first missing ability.

```APIDOC
## CheckAbilities::handle

### Description
Requires the token to have every listed ability. Throws MissingAbilityException for the first missing ability.

### Method
handle

### Endpoint
Laravel\Sanctum\Http\Middleware\CheckAbilities::handle

### Parameters
- **$request** (\Illuminate\Http\Request) - Required - Incoming request.
- **$next** (\Closure) - Required - Next middleware in the pipeline.
- **...$abilities** (mixed... (variadic string)) - Required - Abilities, all of which must be granted.

### Return Type
\Illuminate\Http\Response - the response of $next($request) when authorized.

### Throws
- \Illuminate\Auth\AuthenticationException (no message) when ! $request->user() || ! $request->user()->currentAccessToken().
- \Laravel\Sanctum\Exceptions\MissingAbilityException($ability) for the first ability the token lacks.

### Example
php
Route::middleware(['auth:sanctum', 'abilities:tickets:create,tickets:update'])
    ->post('/tickets', TicketController::class.'@store');


### Error Handling Example
php
use Laravel\Sanctum\Exceptions\MissingAbilityException;

try {
    $response = $kernel->handle($request);
} catch (MissingAbilityException $e) {
    // $e->abilities() contains the missing ability
    report('Denied ability: '.implode(',', $e->abilities()));
}

```

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

### Constructor signature for NewAccessToken

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/new-access-token.md

The constructor accepts a PersonalAccessToken model and the plain-text token string. Both parameters are promoted to public properties.

```php
public function __construct(public PersonalAccessToken $accessToken, public string $plainTextToken)
```

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

### Legacy route usage with scopes and scope middleware

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/scope-middleware.md

Shows how to apply the deprecated scope middleware in routes. The 'scopes' middleware requires all listed scopes, while 'scope' requires any one of them.

```php
// All scopes required
Route::middleware(['auth:sanctum', 'scopes:tickets:read,tickets:update'])
    ->post('/tickets', TicketController::class.'@store');

// Any scope sufficient
Route::middleware(['auth:sanctum', 'scope:tickets:read,tickets:create'])
    ->get('/tickets', TicketController::class.'@index');
```

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

### Sanctum::currentRequestHost() method signature

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/sanctum.md

Declares the public static method currentRequestHost() that returns a string. It returns the placeholder token ',__SANCTUM_CURRENT_REQUEST_HOST__' which is replaced with the request host at runtime.

```php
public static function currentRequestHost()
```

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

### Build Sanctum guard inside RequestGuard

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/guard.md

Constructs the Sanctum guard as a RequestGuard with a Guard instance, the current request, and a user provider. Uses sanctum.expiration and sanctum.last_used_at configuration values.

```php
new RequestGuard(
    new Guard($auth, config('sanctum.expiration'), $config['provider'], config('sanctum.last_used_at', true)),
    request(),
    $auth->createUserProvider($config['provider'] ?? null)
)
```

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

### AuthenticateSession::__construct

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/frontend-middleware.md

Constructor that injects the authentication factory used to resolve guards.

```APIDOC
## `__construct(AuthFactory $auth)`

### Description
Constructor for the AuthenticateSession middleware. Injects the authentication factory used to resolve guards.

### Method
Constructor

### Parameters
- **$auth** (AuthFactory) - Required - The authentication factory (Illuminate\Contracts\Auth\Factory).

### Source
`src/Http/Middleware/AuthenticateSession.php:21`
```

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

### Sanctum::actingAs() method signature

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/sanctum.md

Declares the public static method actingAs($user, $abilities = [], $guard = 'sanctum') that returns the same $user instance. It attaches a mocked token with the given abilities, sets the user on the guard, and makes that guard the default.

```php
public static function actingAs($user, $abilities = [], $guard = 'sanctum')
```

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

### Constructor signature for TokenAuthenticated

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/events.md

The constructor accepts a PersonalAccessToken instance and promotes it to a public property. The event carries no other data.

```php
public function __construct(public $token)
```

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

### MissingAbilityException abilities() method

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/exceptions.md

Returns the wrapped ability list as an array.

```php
public function abilities()
```

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

### Sanctum::currentRequestHost() usage in config/sanctum.php

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/sanctum.md

Shows how to use Sanctum::currentRequestHost() in the config/sanctum.php 'stateful' domain list. The placeholder is replaced by EnsureFrontendRequestsAreStateful::fromFrontend() with $request->getHttpHost() at request time.

```php
'stateful' => explode(',', env('SANCTUM_STATEFUL_DOMAINS', sprintf(
    '%s%s',
    'localhost,localhost:3000,127.0.0.1,::1',
    Sanctum::currentRequestHost(),
))),
```

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

### SPA bootstrap with axios

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/csrf-cookie-controller.md

Fetches the CSRF cookie before login so the browser stores the XSRF-TOKEN cookie, which is then sent automatically with subsequent requests.

```javascript
await axios.get('/sanctum/csrf-cookie');

await axios.post('/login', { email, password });
```

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

### Publishing Sanctum assets via artisan vendor:publish

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

Commands to publish Sanctum migrations and config files. Use the 'sanctum-migrations' tag for migrations and 'sanctum-config' for the config file.

```bash
php artisan vendor:publish --tag=sanctum-migrations
php artisan vendor:publish --tag=sanctum-config
```

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

### NewAccessToken::__construct

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/new-access-token.md

Creates a new NewAccessToken instance with the given PersonalAccessToken model and plain-text token string.

```APIDOC
## NewAccessToken::__construct

### Description
Creates a new NewAccessToken value object combining the persisted token model with the one-time plain-text token string.

### Method
Constructor

### Signature
```php
public function __construct(public PersonalAccessToken $accessToken, public string $plainTextToken)
```

### Parameters
- **$accessToken** (\Laravel\Sanctum\PersonalAccessToken) - Required - The persisted Eloquent token model (contains the SHA-256 hash, never the plain text).
- **$plainTextToken** (string) - Required - The plain-text token of the form `{id}|{40 random chars}{crc32b checksum}`, with optional configured prefix. Shown to the client exactly once.

### Description
Both promoted parameters become public readonly-style properties (`$newToken->accessToken`, `$newToken->plainTextToken`).

### Source
`src/NewAccessToken.php:16`
```

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

### cant()

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/transient-token.md

Always returns false, the negation of can(). The $ability parameter is ignored.

```APIDOC
## `cant()`

### Description
Always returns `false` — the negation of `can()`.

### Method
`cant`

### Signature
```php
public function cant($ability)
```

### Parameters
- **$ability** (string) - Required - The ability to check (ignored by the implementation).

### Return Type
`bool` - always `false`.

### Source
`src/TransientToken.php:26`
```

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

### AuthenticateSession constructor

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/frontend-middleware.md

Constructor for the AuthenticateSession middleware. Accepts an AuthFactory instance (Illuminate\Contracts\Auth\Factory).

```php
public function __construct(protected AuthFactory $auth)
```

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

### Sanctum::currentRequestHost()

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/sanctum.md

Returns the placeholder token `,__SANCTUM_CURRENT_REQUEST_HOST__` (i.e. `',' . static::$currentRequestHostPlaceholder`). When this value appears in `config('sanctum.stateful')`, `EnsureFrontendRequestsAreStateful::fromFrontend()` replaces it with `$request->getHttpHost()` at request time.

```APIDOC
## Sanctum::currentRequestHost()

### Description
Returns the placeholder token `,__SANCTUM_CURRENT_REQUEST_HOST__` (i.e. `',' . static::$currentRequestHostPlaceholder`). When this value appears in `config('sanctum.stateful')`, `EnsureFrontendRequestsAreStateful::fromFrontend()` replaces it with `$request->getHttpHost()` at request time.

### Method
Static method

### Signature
```php
public static function currentRequestHost()
```

### Parameters
None

### Return Value
- **Type:** `string`
- **Description:** The placeholder token `,__SANCTUM_CURRENT_REQUEST_HOST__`.

### Example
```php
'stateful' => explode(',', env('SANCTUM_STATEFUL_DOMAINS', sprintf(
    '%s%s',
    'localhost,localhost:3000,127.0.0.1,::1',
    Sanctum::currentRequestHost(),
))),
```

### Source
`src/Sanctum.php:57`
```

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

### CsrfCookieController show method

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/endpoints.md

Returns a 204 response, choosing between JsonResponse and Response based on the request's expected content type.

```php
public function show(Request $request)
{
    if ($request->expectsJson()) {
        return new JsonResponse(status: 204);
    }

    return new Response(status: 204);
}
```

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

### Guard constructor

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/guard.md

Defines the constructor for the Sanctum Guard. Accepts an AuthFactory, optional expiration, provider, and trackLastUsedAt flag.

```php
public function __construct(protected AuthFactory $auth, protected $expiration = null, protected $provider = null, protected $trackLastUsedAt = true)
```

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

### CheckScopes::handle

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/scope-middleware.md

Requires the token to have every listed scope. Delegates to CheckAbilities and converts MissingAbilityException to MissingScopeException.

```APIDOC
## CheckScopes::handle

### Description
Requires the token to have **every** listed scope. Delegates to CheckAbilities and converts MissingAbilityException to MissingScopeException.

### Method
handle

### Endpoint
Laravel\Sanctum\Http\Middleware\CheckScopes::handle

### Parameters
- **$request** (\Illuminate\Http\Request) - Required - The incoming request.
- **$next** (\Closure) - Required - The next middleware closure.
- **...$scopes** (string) - Required - Variadic list of required scopes.

### Return Type
\Illuminate\Http\Response - Passthrough of CheckAbilities's response.

### Throws
- \Illuminate\Auth\AuthenticationException - When the user is not authenticated or has no current access token.
- \Laravel\Sanctum\Exceptions\MissingScopeException - When any scope is missing; payload is the wrapped ability/scopes array.

### Example
```php
Route::middleware(['auth:sanctum', 'scopes:tickets:read,tickets:update'])
    ->post('/tickets', TicketController::class.'@store');
```
```

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

### Register method: merge sanctum guard config

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

Merges the 'sanctum' guard definition into 'auth.guards'. Existing 'auth.guards.sanctum' keys in the application config override the defaults. Called during the provider's register() method.

```php
config([
    'auth.guards.sanctum' => array_merge([
        'driver' => 'sanctum',
        'provider' => null,
    ], config('auth.guards.sanctum', [])),
]);
```

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

### generateTokenString() method signature

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

Declares the public method that builds the plain-text token as {config('sanctum.token_prefix', '')}{Str::random(40)}{hash('crc32b', $tokenEntropy)}. Returns a string of about 45 characters.

```php
public function generateTokenString()
```

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

### can()

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/transient-token.md

Always returns true, granting every ability to the user. The $ability parameter is ignored.

```APIDOC
## `can()`

### Description
Always returns `true`, regardless of the value of `$ability`.

### Method
`can`

### Signature
```php
public function can($ability)
```

### Parameters
- **$ability** (string) - Required - The ability to check (ignored by the implementation).

### Return Type
`bool` - always `true`.

### Source
`src/TransientToken.php:15`
```

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

### Authorization check using can()

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/personal-access-token.md

Uses the model directly to authorize a token for a specific ability.

```php
$token = PersonalAccessToken::findToken($plainTextToken);

if ($token && $token->can('tickets:create')) {
    // authorized
}
```

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

### AuthenticateSession::handle

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/frontend-middleware.md

Middleware entry point that re-validates the user's password hash stored in the session and force-logs-out if the stored hash no longer matches.

```APIDOC
## `handle(Request $request, Closure $next): Response`

### Description
Middleware entry point. For requests with a session and a user, it re-validates the user's password hash stored in the session and force-logs-out if the stored hash no longer matches (e.g., password changed in another session).

### Method
handle

### Parameters
- **$request** (\Illuminate\Http\Request) - Required - The incoming HTTP request.
- **$next** (\Closure(\Illuminate\Http\Request): (\Symfony\Component\HttpFoundation\Response)) - Required - The next middleware or controller closure.

### Return Type
\Symfony\Component\HttpFoundation\Response

### Throws
- **\Illuminate\Auth\AuthenticationException** - Thrown with message 'Unauthenticated.' and guards `[...\SessionGuard names, 'sanctum']` when any stateful guard's stored `password_hash_{guard}` session value fails validation.

### Behavior
- No session or no user → passes through immediately.
- Filters `config('sanctum.guard')` guards to `SessionGuard` instances.
- Any guard whose stored session hash is invalid triggers `logoutCurrentDevice()` on each invalid guard, flushes the session, and throws `AuthenticationException`.
- On success, after `$next`, stores the current password hash for the first guard that has a user (`password_hash_{guard}` session key).

### Source
`src/Http/Middleware/AuthenticateSession.php:32`
```

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

### can() method signature

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/personal-access-token.md

Checks if the token has a given ability, returning true for wildcard or strict match.

```php
public function can($ability)
```

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

### cant() method signature

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/personal-access-token.md

Returns the negation of can() for the given ability.

```php
public function cant($ability)
```

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

### Dispatch site in Guard::__invoke()

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/events.md

Shows the bearer phase of the guard where the event is dispatched after token validation and before last_used_at is updated.

```php
$tokenable = $accessToken->tokenable->withAccessToken(
    $accessToken
);

event(new TokenAuthenticated($accessToken));

if ($this->trackLastUsedAt) {
    $this->updateLastUsedAt($accessToken);
}

return $tokenable;
```

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

### frontendMiddleware() composed middleware array

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/frontend-middleware.md

The array of middleware composed by frontendMiddleware(), deduplicated, filtered, and order preserved. Includes a leading closure that flags the request with 'sanctum' attribute.

```php
[
    config('sanctum.middleware.encrypt_cookies', \Illuminate\Cookie\Middleware\EncryptCookies::class),
    \Illuminate\Cookie\Middleware\AddQueuedCookiesToResponse::class,
    \Illuminate\Session\Middleware\StartSession::class,
    config('sanctum.middleware.validate_csrf_token', config('sanctum.middleware.verify_csrf_token', \Illuminate\Foundation\Http\Middleware\VerifyCsrfToken::class)),
    config('sanctum.middleware.authenticate_session'),
]
```

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

### Laravel\Sanctum\Http\Middleware\CheckForAnyAbility::handle

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/ability-middleware.md

Requires the token to have at least one of the listed abilities. Throws MissingAbilityException with the array of requested abilities when none match.

```APIDOC
## CheckForAnyAbility::handle

### Description
Requires the token to have at least one of the listed abilities. Throws MissingAbilityException with the array of requested abilities when none match.

### Method
handle

### Endpoint
Laravel\Sanctum\Http\Middleware\CheckForAnyAbility::handle

### Parameters
- **$request** (\Illuminate\Http\Request) - Required - Incoming request.
- **$next** (\Closure) - Required - Next middleware in the pipeline.
- **...$abilities** (mixed... (variadic string)) - Required - Abilities, at least one of which must be granted.

### Return Type
\Illuminate\Http\Response - $next($request) as soon as one ability matches.

### Throws
- \Illuminate\Auth\AuthenticationException (no message) when ! $request->user() || ! $request->user()->currentAccessToken().
- \Laravel\Sanctum\Exceptions\MissingAbilityException($abilities) - constructed with the array of requested abilities when none match.

### Example
php
Route::middleware(['auth:sanctum', 'ability:tickets:create,tickets:update'])
    ->post('/tickets', TicketController::class.'@store');

```

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

### MissingScopeException constructor

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/exceptions.md

Constructor for MissingScopeException. Accepts an array or string of scopes and an optional message.

```php
public function __construct(protected $scopes = [], $message = 'Invalid scope(s) provided.')
```

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

### createToken() method signature

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

Signature of the createToken() method, which creates a new personal access token with the given name, abilities, and optional expiration.

```php
public function createToken(string $name, array $abilities = ['*'], ?DateTimeInterface $expiresAt = null)
```

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

### fromFrontend() method signature

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/frontend-middleware.md

Static method signature for fromFrontend() in EnsureFrontendRequestsAreStateful. Used to classify requests as frontend requests.

```php
public static function fromFrontend($request)
```

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

### Sanctum::actingAs() usage in a test

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/sanctum.md

Shows how to use Sanctum::actingAs() in a test to authenticate a user with specific abilities, then make a JSON request to an endpoint. The user must expose withAccessToken().

```php
use Laravel\Sanctum\Sanctum;

Sanctum::actingAs($user, ['tickets:create', 'tickets:update']);

$this->getJson('/api/tickets');
```

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

### Sanctum::actingAs()

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/sanctum.md

Testing helper. Attaches a mocked token (with the given abilities) to the user, sets the user on the named guard, and makes that guard the default. The mocked token is created via `Mockery::mock(self::personalAccessTokenModel())->shouldIgnoreMissing(false)`; when `'*'` is in `$abilities` every `can()` call returns `true`, otherwise `can($ability)` returns `true` only for the listed abilities.

```APIDOC
## Sanctum::actingAs()

### Description
Testing helper. Attaches a mocked token (with the given abilities) to the user, sets the user on the named guard, and makes that guard the default. The mocked token is created via `Mockery::mock(self::personalAccessTokenModel())->shouldIgnoreMissing(false)`; when `'*'` is in `$abilities` every `can()` call returns `true`, otherwise `can($ability)` returns `true` only for the listed abilities.

### Method
Static method

### Signature
```php
public static function actingAs($user, $abilities = [], $guard = 'sanctum')
```

### Parameters
- **$user** (`\Illuminate\Contracts\Auth\Authenticatable | \Laravel\Sanctum\HasApiTokens`) - Required - The user to act as; must expose `withAccessToken()`.
- **$abilities** (`array`) - Optional (default: `[]`) - Ability list granted to the mock token; `'*'` grants everything.
- **$guard** (`string`) - Optional (default: `'sanctum'`) - Guard name to set the user on and to make the default via `Auth::shouldUse()`.

### Return Value
- **Type:** `\Illuminate\Contracts\Auth\Authenticatable`
- **Description:** The same `$user` instance.

### Side Effects
- Sets `$user->wasRecentlyCreated = false` when set and truthy.
- Calls `app('auth')->guard($guard)->setUser($user)` and `app('auth')->shouldUse($guard)`.

### Example
```php
use Laravel\Sanctum\Sanctum;

Sanctum::actingAs($user, ['tickets:create', 'tickets:update']);

$this->getJson('/api/tickets');
```

### Source
`src/Sanctum.php:70`
```

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

### handle() method declaration

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/prune-expired-command.md

The handle method that executes the pruning logic. It deletes expired tokens in two passes and returns 0 on success.

```php
public function handle()
```

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

### MissingScopeException scopes() method

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/exceptions.md

Returns the wrapped scope list as an array.

```php
public function scopes()
```

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

### HasAbilities interface with can() and cant() methods

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/types.md

Defines the contract for token objects to check abilities. Used by personal access tokens, transient tokens, and mocked tokens from Sanctum::actingAs().

```php
interface HasAbilities
{
    /**
     * Determine if the token has a given ability.
     *
     * @param  string  $ability
     * @return bool
     */
    public function can($ability);

    /**
     * Determine if the token is missing a given ability.
     *
     * @param  string  $ability
     * @return bool
     */
    public function cant($ability);
}
```

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

### Stateful request middleware pipeline

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/configuration.md

Defines the middleware pipeline for stateful requests, composed at runtime by EnsureFrontendRequestsAreStateful::frontendMiddleware(). Order matters; the pipeline is preceded by a closure that flags the request with 'sanctum'.

```php
config('sanctum.middleware.encrypt_cookies', EncryptCookies::class),
Illuminate\Cookie\Middleware\AddQueuedCookiesToResponse::class,
Illuminate\Session\Middleware\StartSession::class,
config('sanctum.middleware.validate_csrf_token',
    config('sanctum.middleware.verify_csrf_token', VerifyCsrfToken::class)),
config('sanctum.middleware.authenticate_session'),
```

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

### CheckAbilities handle method signature

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/ability-middleware.md

Signature for the handle method of Laravel\Sanctum\Http\Middleware\CheckAbilities. Requires the token to have every listed ability. Throws AuthenticationException when no user or token is present, and MissingAbilityException for the first missing ability.

```php
public function handle($request, $next, ...$abilities)
```

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

### handle() method signature

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/frontend-middleware.md

Signature of the handle() method in EnsureFrontendRequestsAreStateful. It accepts a request and a next callable, and returns a response.

```php
public function handle($request, $next)
```

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

### Default config/sanctum.php configuration

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/configuration.md

Full default configuration for Laravel Sanctum. Defines stateful domains, guard, token expiration, token prefix, and middleware stack. The 'stateful' option uses Sanctum::currentApplicationUrlWithPort() to include the current application URL and port; the commented line shows an alternative using currentRequestHost().

```php
'stateful' => explode(',', env('SANCTUM_STATEFUL_DOMAINS', sprintf(
    '%s%s',
    'localhost,localhost:3000,127.0.0.1,127.0.0.1:8000,::1',
    Sanctum::currentApplicationUrlWithPort(),
    // Sanctum::currentRequestHost(),
))),

'guard' => ['web'],

'expiration' => null,

'token_prefix' => env('SANCTUM_TOKEN_PREFIX', ''),

'middleware' => [
    'authenticate_session' => AuthenticateSession::class,
    'encrypt_cookies' => EncryptCookies::class,
    'validate_csrf_token' => ValidateCsrfToken::class,
],
```

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

### Command signature and description for sanctum:prune-expired

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/prune-expired-command.md

Defines the command's signature and description. The --hours option defaults to 24 and controls the retention window for expired tokens.

```php
protected $signature = 'sanctum:prune-expired {--hours=24 : The number of hours to retain expired Sanctum tokens}';

protected $description = 'Prune tokens expired for more than specified number of hours';
```

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

### findToken() method signature

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/personal-access-token.md

Static method to find a token by its plain or prefixed value.

```php
public static function findToken($token)
```

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

### tokenable() method signature

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/personal-access-token.md

Declares the tokenable() method that returns a morph-to relationship to the owning model.

```php
public function tokenable()
```

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

### tokens()

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

Defines a morph-many relationship to the personal access token model, allowing retrieval and management of all tokens for the user.

```APIDOC
## tokens()

### Description
Defines a morph-many relationship to the token model (`Sanctum::$personalAccessTokenModel`) on the `tokenable` morph. This allows you to retrieve and manage all personal access tokens for the user.

### Method
tokens()

### Return Type
`\Illuminate\Database\Eloquent\Relations\MorphMany<TToken, $this>`

### Example
```php
$user->tokens()->delete(); // revoke all tokens
```
```

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

### tokenCan() method signature

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

Defines the method to check if the current token has a given ability.

```php
public function tokenCan(string $ability)
```

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

### PersonalAccessToken model configuration

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/personal-access-token.md

Defines the Eloquent model with casts for abilities, last_used_at, and expires_at; fillable attributes; and hides the token hash from serialization.

```php
class PersonalAccessToken extends Model implements HasAbilities
{
    protected $casts = [
        'abilities' => 'json',
        'last_used_at' => 'datetime',
        'expires_at' => 'datetime',
    ];

    protected $fillable = [
        'name',
        'token',
        'abilities',
        'expires_at',
    ];

    protected $hidden = [
        'token',
    ];
}
```

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

### tokens() method signature

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

Defines the relationship to the token model as a morph-many.

```php
public function tokens()
```

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

### withAccessToken() method signature

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

Declares the public method that attaches the given token as the current token for the request and returns $this.

```php
public function withAccessToken($accessToken)
```

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

### tokenCant()

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

Logical negation of tokenCan(). Checks if the token does not have the given ability.

```APIDOC
## `tokenCant()`

### Description
Logical negation of `tokenCan()`. Returns `true` if the token does not have the given ability.

### Method
`tokenCant`

### Parameters
- **$ability** (string) - Required - The ability to check.

### Return Type
`bool`

### Example
```php
if ($user->tokenCant('admin')) {
    abort(403, 'Admin ability required.');
}
```
```

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

### currentAccessToken() method signature

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

Declares the public method that returns the token attached to the current request, or null when none.

```php
public function currentAccessToken()
```

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

### tokenCant() method signature

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

Signature of the tokenCant() method, which returns a boolean indicating whether the token does not have the given ability.

```php
public function tokenCant(string $ability)
```

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

### frontendMiddleware() method signature

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/frontend-middleware.md

Signature of the protected frontendMiddleware() method in EnsureFrontendRequestsAreStateful.

```php
protected function frontendMiddleware()
```

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

### Axios withCredentials enabled

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/csrf-cookie-controller.md

Enables withCredentials so the XSRF-TOKEN cookie is persisted and resent with requests.

```javascript
axios.defaults.withCredentials = true;

await axios.get('/sanctum/csrf-cookie');

await axios.post('/login', { email, password });
```

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

### toArray() method signature

Source: https://github.com/laravel/sanctum/blob/4.x/_autodocs/api-reference/new-access-token.md

Declares the toArray() method that serializes the object to an array with 'accessToken' and 'plainTextToken' keys.

```php
public function toArray()
```
Tokens:
Raw