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

# What Is Laravel Authentication?

> Learn the Identity, Principal, Device, and Tenant model that Laravel Authentication uses to provide contextual stateless auth for Laravel apps.

Most authentication packages collapse "who you are" and "who you're acting as" into a single user object. Laravel Authentication separates them. It gives your Laravel application a stateless authentication layer built around five distinct concepts — Identity, Principal, Device, Tenant, and Type — all exposed through the standard `Auth` facade with no new API to learn. You keep `Auth::check()`, `Auth::user()`, standard middleware, and standard events; the package adds contextual accessors and ships hardened `jwt` and `basic` guards on top.

## Why contextual auth

A single-model approach works fine for simple apps, but breaks down when the same person needs to act on behalf of different tenants, memberships, or roles — or when you need to track which client device issued a request for replay protection and last-seen tracking. By separating Identity from Principal, you can model the full "logged in as X, acting as Y inside tenant Z" relationship cleanly, and the package's JWT pipeline encodes that context directly into the token claims.

## Core concepts

| Concept       | What it is                                                                                 |
| ------------- | ------------------------------------------------------------------------------------------ |
| **Identity**  | Who logged in. The account behind the request — a person or a service account.             |
| **Principal** | Who the request is acting as. Often the same as the identity; can be a role or membership. |
| **Device**    | Which client obtained the login — a browser, a mobile app, a CLI session.                  |
| **Tenant**    | The isolation boundary the principal acts within. Optional, for multi-tenant apps.         |
| **Type**      | An optional categorical label on the tenant — e.g. `"staff"` vs `"customer"`.              |

## Adoption modes

The package supports two adoption shapes with the same guards, so you can start simple and grow without re-platforming.

**2D mode (identity is the principal)** is the simplest shape. One model implements both `Identity` and `Principal`. The user who logs in is the actor on whose behalf the request runs. `Auth::identity()` and `Auth::principal()` return the same object.

**3D mode (identity → principal → tenant)** is for multi-tenant apps where the logged-in human operates on behalf of a tenant-scoped actor. The identity and principal are separate models. A `pid` claim in the JWT encodes which principal is active, and `Auth::principal()` returns that tenant-scoped membership or role. `Auth::tenant()` returns the tenant the principal belongs to.

## Guards

Two sessionless guards are included, registered via `auth.guards.*.driver` in `config/auth.php`:

* **`jwt`** — Bearer token guard. Access tokens are self-verifying JWTs. The guard rehydrates identity and principal on every bearer request with no server-side access-token store. Refresh-token rotation is device-backed and stateful.
* **`basic`** — HTTP Basic guard. Wraps credential validation in a constant-time `Timebox` to prevent timing side-channels. Supports per-guard identifier fields (`email`, `username`, `key_id`, etc.).

## Contextual accessors

Import the package's `Auth` facade to get IDE-friendly autocompletion on the contextual methods:

```php theme={null}
use SineMacula\Laravel\Authentication\Facades\Auth;

Auth::check();       // bool         — standard Laravel
Auth::user();        // Identity|null — standard Laravel

Auth::identity();    // Identity|null  — the authenticated subject
Auth::principal();   // Principal|null — the acting principal
Auth::device();      // Device|null    — the issuing device
Auth::tenant();      // Tenant|null    — the tenant the principal acts within
Auth::type();        // string|null    — the tenant's type, when HasType is implemented
```

Both facades resolve through the same `auth` container key. You can keep the Illuminate facade for `Auth::check()` and `Auth::user()` — the contextual accessors only become available when you swap to the package facade.

## Requirements

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

<CardGroup cols={2}>
  <Card title="Installation" icon="download" href="/installation">
    Install via Composer, publish config and migrations, and set your JWT secret.
  </Card>

  <Card title="Quick start" icon="bolt" href="/quickstart">
    Wire up your first JWT guard and issue your first access token.
  </Card>
</CardGroup>