> ## 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.

# Laravel Authentication: Contextual Stateless Auth

> Stateless JWT and HTTP Basic guards for Laravel that expose Identity, Principal, Device, and Tenant contexts through the standard Auth facade.

Laravel Authentication gives your Laravel application a hardened, stateless authentication layer that goes beyond a simple "who is logged in?" check. Instead of collapsing everything into a single user object, it separates the **Identity** (who authenticated), the **Principal** (who is acting), the **Device** (which client issued the request), and the **Tenant** (the isolation boundary) — all accessible through familiar `Auth::` calls.

<CardGroup cols={2}>
  <Card title="Installation" icon="download" href="/installation">
    Add the package via Composer, publish config, and run migrations in under five minutes.
  </Card>

  <Card title="Quick Start" icon="bolt" href="/quickstart">
    Wire up your first JWT guard and issue your first access token with a minimal working example.
  </Card>

  <Card title="Core Concepts" icon="book-open" href="/concepts/identity-principal-device">
    Understand Identity, Principal, Device, and Tenant before writing a single line of auth code.
  </Card>

  <Card title="Guides" icon="map" href="/guides/2d-setup">
    Step-by-step walkthroughs for 2D simple apps, 3D multi-tenant apps, token issuance, and more.
  </Card>
</CardGroup>

## What you get

Laravel Authentication drops into Laravel's existing auth machinery — no new API to learn. You keep `Auth::check()`, `Auth::user()`, `auth()->guard('api')`, standard middleware, and standard events. On top of that you get:

* **Two sessionless guards** — `jwt` (Bearer token) and `basic` (HTTP Basic), registered via `auth.guards.*.driver`
* **Contextual accessors** — `Auth::identity()`, `Auth::principal()`, `Auth::device()`, `Auth::tenant()`, `Auth::type()`
* **Hardened JWT pipeline** — enforces `iss`, `aud`, `typ`, `exp`, and leeway on every parse; fails closed on empty secrets
* **Refresh-token rotation** — atomic per-device rotation with replay detection and machine-readable failure events
* **Kid-based key rotation** — issue under one kid, verify against a map, retire old kids gracefully
* **Pluggable everything** — swap the device model, principal resolver, identifier field, or table names

<Steps>
  <Step title="Install the package">
    Run `composer require sinemacula/laravel-authentication` and publish config and migrations.
  </Step>

  <Step title="Configure your guards">
    Register `jwt` or `basic` drivers in `config/auth.php` and set your JWT secret in `.env`.
  </Step>

  <Step title="Implement your identity model">
    Add the `Identity` contract and `Authenticatable` trait to your user model.
  </Step>

  <Step title="Issue and verify tokens">
    Call `Auth::jwt('api')->issueAccessToken(...)` to mint tokens and let the guard handle bearer verification automatically.
  </Step>
</Steps>