• Laravel 11+ application
• PHP 8.2+ with extensions:

  mbstring

  ,

  openssl

  ,

  json

• Composer installed
• Auth0 API resource configured (not an Application - must be an API)
• If you don't have Auth0 set up yet, use the

  auth0-quickstart

  skill first

STOP - ask the user before proceeding.

Ask exactly this question and wait for their answer before doing anything else:

"How would you like to create the Auth0 API resource?

1. Automated - I'll run Auth0 CLI scripts that create the resource and write the exact values to your

   .env

   automatically.
2. Manual - You create the API yourself in the Auth0 Dashboard (or via

   auth0 apis create

   ) and provide me the Domain and Audience.

Which do you prefer? (1 = Automated / 2 = Manual)"

Do NOT proceed to any setup steps until the user has answered. Do NOT default to manual.

.env

auth0 apis create \
  --name "My Laravel API" \
  --identifier https://my-api.example.com \
  --json

config/auth.php

'guards' => [
    'web' => [
        'driver' => 'session',
        'provider' => 'users',
    ],
    'auth0-api' => [
        'driver' => 'auth0.authorizer',
        'provider' => 'auth0-provider',
        'configuration' => 'api',
    ],
],

'providers' => [
    'users' => [
        'driver' => 'eloquent',
        'model' => App\Models\User::class,
    ],
    'auth0-provider' => [
        'driver' => 'auth0.provider',
        'repository' => 'auth0.repository',
    ],
],

• driver

  must be

  auth0.authorizer

  (not

  auth0.authenticator

  which is for web apps)

• configuration

  must be

  'api'

  which maps to the

  api

  guard in

  config/auth0.php

• The SDK auto-registers an

  auth0-api

  guard with this config, but defining it explicitly is clearer

hasScope()

hasPermission()

Route::middleware('auth:auth0-api')->group(function () {
    Route::get('/messages', function () {
        $guard = auth('auth0-api');

        if (!$guard->hasScope('read:messages')) {
            return response()->json(['error' => 'insufficient_scope'], 403);
        }

        return response()->json(['messages' => []]);
    });

    Route::delete('/users/{id}', function (string $id) {
        $guard = auth('auth0-api');

        if (!$guard->hasPermission('delete:users')) {
            return response()->json(['error' => 'insufficient_permissions'], 403);
        }

        return response()->json(['deleted' => $id]);
    });
});

• hasScope()

  checks the

  scope

  claim (space-separated string in the JWT)

• hasPermission()

  checks the

  permissions

  claim (array, requires RBAC enabled on the API in Auth0 Dashboard)

StatelessUser

Route::middleware('auth:auth0-api')->get('/profile', function () {
    $user = auth('auth0-api')->user();

    return response()->json([
        'sub' => $user->getAuthIdentifier(),
        'email' => $user->email,
        'permissions' => $user->permissions ?? [],
        'all_claims' => $user->jsonSerialize(),
    ]);
});

• $user->getAuthIdentifier()

  - Returns

  sub

  claim

• $user->claim_name

  - Dynamic property access via

  __get

• $user->getAttribute('claim_name')

  - Explicit access

• $user->jsonSerialize()

  - All claims as array

Agent instruction: Start the Laravel dev server and verify the basic endpoints work without credentials:

bash

php artisan serve &
sleep 2
curl -s -H "Accept: application/json" http://localhost:8000/api/public
curl -s -o /dev/null -w "%{http_code}" -H "Accept: application/json" http://localhost:8000/api/private

• /api/public

  should return

  {"message":"Public endpoint - no authentication required"}

• /api/private

  should return HTTP 401

Important: The

-H "Accept: application/json"

header is required. Without it, Laravel's

Authenticate

middleware returns a 302 redirect instead of 401.

If both pass, the guard is working. Kill the background server when done:

bash

kill %1 2>/dev/null

Failcheck: If the server fails to start or responses are unexpected, check that

config/auth0.php

exists and

.env

has

AUTH0_DOMAIN

and

AUTH0_AUDIENCE

set. After 5-6 failed iterations, use

AskUserQuestion

.

Agent instruction: STOP - ask after basic tests pass.

Once public/401 tests pass, ask the user:

"Your API is set up and the guard is working (public returns 200, private returns 401 without a token). Would you like me to help you set up testing with a real access token?

1. Yes - I'll help you configure an M2M application to get test tokens.
2. No - I'm done for now.

Which do you prefer?"

Do NOT proceed with M2M/token setup unless the user says yes.

Agent instruction (M2M app setup - only if user wants testing):

If the user chose to set up testing, ask:

"To test your protected endpoints, you need a Machine-to-Machine (M2M) application authorized to request tokens for this API.

1. Create new - I'll create a new M2M application and authorize it for this API.
2. Use existing - You already have an M2M application. Provide the Client ID and I'll authorize it for this API.

Which do you prefer? (1 = Create new / 2 = Use existing)"

Do NOT proceed until the user answers.

If the user chose "Create new":

bash

auth0 apps create \
  --name "${PWD##*/} (Test App)" \
  --type m2m \
  --no-input --json

Parse JSON with

jq

to extract

client_id

. Do NOT use

--reveal-secrets

. Then create a client grant:

bash

auth0 api post "client-grants" --data '{
  "client_id": "<CLIENT_ID>",
  "audience": "<API_IDENTIFIER>",
  "scope": ["<SCOPES>"]
}'

If the user chose "Use existing": Ask for Client ID. Create a client grant (409 conflict = already authorized, fine).

Agent instruction (TOKEN ISOLATION - CRITICAL):

The agent MUST NEVER directly see or display access token values.

• Do NOT run

  auth0 test token

  on its own
• Do NOT ask the user to paste their token
• Do NOT echo or store the token value

Secure testing (single-command chain):

bash

php artisan serve &
sleep 2
TEST_TOKEN=$(auth0 test token <M2M_CLIENT_ID> --audience <AUDIENCE> --scopes <SCOPE1,SCOPE2> 2>/dev/null | grep -o 'ey[A-Za-z0-9_-]*\.[A-Za-z0-9_-]*\.[A-Za-z0-9_-]*') && \
[ -n "$TEST_TOKEN" ] && echo "Token acquired (${#TEST_TOKEN} chars)" && \
curl -s -H "Accept: application/json" -H "Authorization: Bearer $TEST_TOKEN" http://localhost:8000/api/private
kill %1 2>/dev/null

If the user does NOT ask to test, provide commands for them to run manually:

bash

auth0 test token <CLIENT_ID> --audience <AUDIENCE> --scopes <SCOPE1,SCOPE2>
curl -H "Accept: application/json" -H "Authorization: Bearer <PASTE_TOKEN_HERE>" http://localhost:8000/api/private

php artisan serve

curl -H "Accept: application/json" http://localhost:8000/api/public

curl -H "Accept: application/json" http://localhost:8000/api/private

Accept: application/json

curl http://localhost:8000/api/private \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

• auth0-laravel

  - For Laravel web apps with login/logout using session-based auth

• auth0-php-api

  - For plain PHP APIs without Laravel

• auth0-quickstart

  - Initial Auth0 setup

• auth0-mfa

  - Add Multi-Factor Authentication

• auth0-cli

  - Manage Auth0 resources from the terminal

config/auth.php

'guards' => [
    'auth0-api' => [
        'driver' => 'auth0.authorizer',
        'provider' => 'auth0-provider',
        'configuration' => 'api',
    ],
],
'providers' => [
    'auth0-provider' => [
        'driver' => 'auth0.provider',
        'repository' => 'auth0.repository',
    ],
],

Route::middleware('auth:auth0-api')->group(function () {
    Route::get('/resource', fn() => response()->json([...]));
});

$guard = auth('auth0-api');
$guard->hasScope('read:messages');       // checks scope claim
$guard->hasPermission('delete:users');   // checks permissions claim (RBAC)

$user = auth('auth0-api')->user();
$user->getAuthIdentifier();   // sub
$user->email;                 // any claim via __get
$user->getAttribute('iss');   // explicit claim access

• AUTH0_DOMAIN

  - Auth0 tenant domain (e.g.

  tenant.us.auth0.com

  )

• AUTH0_AUDIENCE

  - API identifier (e.g.

  https://api.example.com

  )

• Protect routes ->

  auth:auth0-api

  middleware (see Step 7)
• Scope enforcement ->

  hasScope()

  (see Step 8)
• Permission enforcement ->

  hasPermission()

  (see Step 8)
• Advanced configuration -> API Reference

• Setup Guide - Auth0 CLI setup, environment configuration, getting test tokens
• Integration Guide - Scopes, permissions, CORS, custom user repositories, error handling, multi-guard
• API Reference - Complete AuthorizationGuard API, StatelessUser, CredentialEntity, configuration options

• Auth0 Laravel API Quickstart
• SDK GitHub Repository
• SDK on Packagist
• Access Tokens Guide