> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sinemacula.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Install Laravel Authentication

> Install the sinemacula/laravel-authentication package via Composer, publish the config file and device migration, then run migrate.

Laravel Authentication is a standard Composer package. Installing it takes four steps: require the package, publish the config, publish the device migration, and run `migrate`. If you only need access tokens with no device tracking or refresh rotation — the common pattern for M2M APIs and short-lived session flows — you can skip the migration entirely.

<Note>
  **Access-only mode (no devices, no refresh):** If you don't need refresh-token rotation or device tracking, publish only the config and skip the migration. Don't implement `HasDevices` on your identity model. `Auth::device()` will always return `null`, but the full `Auth::identity()`, `Auth::principal()`, `Auth::tenant()`, and `Auth::type()` surface still works. You can add device support later — it's additive, not a rewrite.
</Note>

## Requirements

* PHP ^8.3 (extensions: `hash`, `mbstring`, `openssl`)
* Laravel ^12.40 || ^13.3

## Steps

<Steps>
  <Step title="Require the package">
    Add the package to your application via Composer:

    ```bash theme={null}
    composer require sinemacula/laravel-authentication
    ```
  </Step>

  <Step title="Publish the config file">
    Publish `config/authentication.php` to your application:

    ```bash theme={null}
    php artisan vendor:publish --tag=authentication-config
    ```

    This creates `config/authentication.php` with defaults for JWT signing, device tracking, credential timing, and optional resolution caching.
  </Step>

  <Step title="Publish the device migration">
    Publish the `devices` table migration. Skip this step if you are using access-only mode.

    ```bash theme={null}
    php artisan vendor:publish --tag=authentication-migrations
    ```
  </Step>

  <Step title="Run migrations">
    Apply the published migration to your database. Skip this step if you are using access-only mode.

    ```bash theme={null}
    php artisan migrate
    ```

    This creates the `devices` table, which the package uses for refresh-token rotation, replay detection, and debounced `last_logged_in_at` writes.
  </Step>

  <Step title="Set the JWT secret">
    Add your JWT signing secret to `.env`. The package fails closed when the secret is empty or invalid — silent acceptance of forged tokens is never the default.

    ```dotenv theme={null}
    AUTHENTICATION_JWT_SECRET="a-strong-random-value-of-at-least-32-bytes"
    ```

    Generate a suitable value with:

    ```bash theme={null}
    php -r "echo base64_encode(random_bytes(40)) . PHP_EOL;"
    ```
  </Step>
</Steps>

## Next steps

With the package installed and the secret set, register your first guard in `config/auth.php`:

```php theme={null}
'guards' => [
    'api' => [
        'driver'   => 'jwt',
        'provider' => 'users',
    ],
],

'providers' => [
    'users' => [
        'driver' => 'model',
        'model'  => App\Models\User::class,
    ],
],
```

Then head to the quick start to implement your identity model and issue your first token.