Download the PHP package pictastudio/auth without Composer

pictastudio/auth

Opinionated API authentication and authorization for Laravel using Sanctum and Spatie roles/permissions.

Features

• Common API auth routes: register, login, logout, current user, forgot/reset password, email verification.
• Dual-mode Sanctum authentication:
  • Stateful cookie/session auth for first-party frontend requests.
  • Bearer token auth for third-party API consumers.
• Config-driven permission generation with pattern {model}:{action}.
• Config-driven role bootstrap with defaults:
  • root (all permissions)
  • admin (all permissions)
  • user (no permissions assigned by default)
• Global helper auth_authorize(...) to run authorization checks from anywhere.
• User model trait to bootstrap Sanctum + Spatie integration quickly.

Installation

Install Auth

Configuration

Permissions are generated from config/picta-auth.php under picta-auth.permissions.

For API-only projects, you can also point notification links to frontend routes:

• AUTH_LIBRARY_FRONTEND_RESET_PASSWORD_URL: frontend page that receives token and email query params.
• AUTH_LIBRARY_FRONTEND_EMAIL_VERIFICATION_URL: frontend page that receives signed verification query params (id, hash, expires, signature).
• If AUTH_LIBRARY_FRONTEND_RESET_PASSWORD_URL is not set and no password.reset route exists, the package falls back to APP_URL + picta-auth.routes.default_reset_password_path (default: /reset-password).

Password reset validation rules are configurable via picta-auth.password_rules:

• AUTH_LIBRARY_ISSUE_TOKEN_BY_DEFAULT (optional): force login responses to always issue (true) or not issue (false) bearer tokens. By default, the package auto-detects: stateful frontend requests get cookie auth, non-stateful requests get bearer tokens.

If you publish the Bruno collection, create your local env file from the template:

bruno/auth/environments/Local.bru is gitignored so personal values are not tracked.

Generated permission names follow:

Generate Permissions and Roles

This command keeps existing records and only creates missing permissions/roles.

User Model Trait

Use the package trait on your User model to get:

• Sanctum API tokens
• Spatie roles/permissions support
• Default guard resolution from picta-auth.guard
• Convenience method: $user->canAuthorize($model, $action)

Global Helper

API Routes

Mounted under /api/auth by default:

• POST /api/auth/register
• POST /api/auth/login
• GET /api/auth/me
• POST /api/auth/logout
• POST /api/auth/forgot-password
• POST /api/auth/reset-password
• POST /api/auth/email/verification-notification
• GET /api/auth/verify-email/{id}/{hash}

Registration

POST /api/auth/register accepts:

• name (string, required)
• email (email, required, unique)
• password (string, required, defaults to picta-auth.password_rules)
• password_confirmation (required when using the default confirmed password rule)

Optional payload fields:

• issue_token (boolean): force token issuance on/off.
• token_name (string): token name when issuing bearer tokens.

Like login, registration defaults to cookie auth for stateful frontend requests and bearer token auth for non-stateful requests.

Login Modes

POST /api/auth/login supports both Sanctum modes:

• First-party frontend (stateful request, Origin/Referer in sanctum.stateful): authenticates with cookies/session by default.
• Third-party clients (non-stateful request): returns a bearer token by default.

Optional payload fields:

• issue_token (boolean): force token issuance on/off.
• token_name (string): token name when issuing bearer tokens.

To use cookie-based SPA auth, make sure your frontend domain is in config/sanctum.php (sanctum.stateful) and keep picta-auth.routes.stateful_middleware enabled.

Frontend Integration (Cookie Auth)

Use this flow when your first-party frontend authenticates with cookies (Sanctum stateful mode) instead of bearer tokens.

1. Backend setup

Set your frontend as a stateful domain and allow cross-site credentials.

Example .env:

Example config/cors.php:

Notes:

• Keep picta-auth.routes.stateful_middleware enabled (default).
• The Sanctum CSRF route is exposed under the same prefix as your auth routes (GET /api/auth/csrf-cookie by default).
• The package will default POST /api/auth/login to cookie auth for these stateful frontend requests.
• For localhost-only development, you can leave SESSION_DOMAIN unset.
• For production subdomains, use a shared session domain (for example .example.com).

2. Frontend request flow

1. Get CSRF cookie: GET /api/auth/csrf-cookie with credentials.
2. Login: POST /api/auth/login with email/password and credentials.
3. Read current user: GET /api/auth/me with credentials.
4. Logout: POST /api/auth/logout with credentials.

3. Frontend example (Axios)

4. Frontend example (Fetch)

5. If login still returns tokens

POST /api/auth/login can still issue bearer tokens when:

• The request is not detected as stateful (missing/mismatched Origin or Referer).
• You explicitly pass issue_token: true.
• You force token mode with AUTH_LIBRARY_ISSUE_TOKEN_BY_DEFAULT=true.

Morph Map

Inside your AppServiceProvider add this to ensure the relation morph map is registered:

Testing