Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs-staging.auth0-mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

Use AI to integrate Auth0

If you use an AI coding assistant like Claude Code, Cursor, or GitHub Copilot, you can add Auth0 authentication automatically in minutes using agent skills.Install:
npx skills add auth0/agent-skills --skill auth0-quickstart --skill auth0-laravel
Then ask your AI assistant:
Add Auth0 authentication to my Laravel app
Your AI assistant will automatically create your Auth0 application, fetch credentials, install auth0/login, configure environment variables, and register authentication routes. Full agent skills documentation →
Prerequisites: Before you begin, ensure you have the following installed:Verify installation: php --version && composer --version

​
Get Started

This quickstart demonstrates how to add Auth0 authentication to a Laravel application. You’ll configure secure login, logout, protected routes, and user profile access using the Auth0 Laravel SDK.
1

Create a new Laravel project

If you already have a Laravel application, skip to Step 2.Create a new Laravel project:
composer create-project laravel/laravel auth0-laravel-app
Open the project directory:
cd auth0-laravel-app
2

Install the Auth0 Laravel SDK

Run the following command in your project directory to install the Auth0 Laravel SDK:
composer require auth0/login:^7 --update-with-all-dependencies
Then publish the SDK configuration file:
php artisan vendor:publish --tag auth0
3

Configure Auth0 credentials

You need to create an Auth0 application and add your credentials to the project. Choose one of the following methods:
4

Add authentication routes

The Auth0 SDK automatically registers the following routes for your application — no additional route configuration is required:
RoutePurpose
/loginInitiates the Auth0 login flow
/logoutLogs out the user and redirects to Auth0
/callbackHandles the Auth0 authentication callback
If your application uses Laravel Breeze, Fortify, or Jetstream, the SDK’s /login, /logout, and /callback routes may conflict with routes registered by those packages. See the SDK README for instructions on manual route registration.
Update routes/web.php to add your home route:
routes/web.php
<?php

use Illuminate\Support\Facades\Route;

Route::get('/', function () {
    if (! auth()->check()) {
        return response('You are not logged in. <a href="/login">Log in</a>');
    }

    $user = auth()->user();
    $name = $user->name ?? 'User';
    $email = $user->email ?? '';

    return response("Hello {$name}! Your email address is {$email}.");
});
5

Protect routes with middleware

Use Laravel’s auth middleware to require authentication on any route. You can also enforce specific permissions using the can middleware:
routes/web.php
<?php

use Illuminate\Support\Facades\Route;

// Requires any authenticated user
Route::get('/private', function () {
    return response('Welcome! You are logged in.');
})->middleware('auth');

// Requires authentication AND the 'read:messages' permission
Route::get('/scope', function () {
    return response('You have the read:messages permission.');
})->middleware('auth')->can('read:messages');
Permissions are defined in your Auth0 API settings and assigned to users via roles. See Role-Based Access Control for details.
6

Run your application

php artisan serve
Your application runs at http://localhost:8000. If port 8000 is already in use, run php artisan serve --port=8001 and update your Auth0 application’s Allowed Callback URLs and Allowed Logout URLs to use the new port.
CheckpointOpen http://localhost:8000 in your browser. Try these routes to verify your integration:

​
Troubleshooting

Cause: The callback URL sent to Auth0 doesn’t match any URL in your application’s Allowed Callback URLs list.Fix:
  1. Go to the Auth0 Dashboard → Applications > Applications → your app → Settings
  2. Add http://localhost:8000/callback to Allowed Callback URLs
  3. Click Save Changes
Ensure there are no trailing slashes and that the port matches your running server.
Cause: Session or cookie misconfiguration — the Laravel session isn’t persisting state between the login redirect and callback.Fix:
  1. Ensure your SESSION_DRIVER in .env is set to file, database, or redis (not array)
  2. Clear the config and cache:
php artisan config:clear && php artisan cache:clear
  1. Restart your development server
Cause: The SDK cannot find your Auth0 credentials.Fix: Ensure one of the following exists in your project root:
  • A .env file with AUTH0_DOMAIN, AUTH0_CLIENT_ID, and AUTH0_CLIENT_SECRET
  • A .auth0.app.json file generated by the Auth0 CLI
After updating .env, clear the config cache:
php artisan config:clear
Cause: The SDK’s routes aren’t registered, usually because the service provider didn’t load.Fix:
  1. Confirm you ran php artisan vendor:publish --tag auth0
  2. Verify package auto-discovery is enabled (check composer.json for "dont-discover": [])
  3. Run php artisan route:list | grep auth0 to confirm the routes are registered
  4. If routes are missing, manually register the service provider. In Laravel 11+, add it to bootstrap/providers.php:
bootstrap/providers.php
return [
    App\Providers\AppServiceProvider::class,
    Auth0\Laravel\Auth0ServiceProvider::class,
];

​
Advanced Usage

You can update user information using the Auth0 Management API. All Management API endpoints are accessible via the SDK’s Auth0::management() method.Before making Management API calls, authorize your application to access the Management API:
  1. Go to the Auth0 Dashboard → Applications > APIs → Auth0 Management API
  2. Select the Machine to Machine Applications tab
  3. Authorize your Laravel application and grant the read:users and update:users scopes
routes/web.php
<?php

use Auth0\Laravel\Facade\Auth0;
use Illuminate\Support\Facades\Route;

Route::get('/colors', function () {
    $colors = ['red', 'blue', 'green', 'black', 'white', 'yellow', 'purple', 'orange'];

    $users = Auth0::management()->users();

    // Update the authenticated user's metadata with a random favorite color
    $users->update(
        id: auth()->id(),
        body: [
            'user_metadata' => [
                'color' => $colors[random_int(0, count($colors) - 1)],
            ],
        ]
    );

    // Retrieve and display the updated metadata
    $metadata = Auth0::json($users->get(auth()->id()));
    $color = $metadata['user_metadata']['color'] ?? 'unknown';
    $name = auth()->user()->name;

    return response("Hello {$name}! Your favorite color is {$color}.");
})->middleware('auth');
A full reference of all Management API methods is available in the SDK documentation.
The SDK supports custom user models and repositories, letting you store and retrieve users from your own database while keeping Auth0 as the identity provider.See User Repositories and Models for the full implementation guide.
The SDK raises events at key points in the authentication lifecycle — on login, logout, token refresh, and more — allowing you to fully customize behavior without modifying core SDK code.See Hooking Events for a full list of events and implementation examples.
Use Auth0 RBAC to assign permissions to users via roles, then enforce them in Laravel using the can middleware:
routes/web.php
<?php

use Illuminate\Support\Facades\Route;

Route::get('/admin', function () {
    return response('Admin area.');
})->middleware('auth')->can('admin:dashboard');
To set up RBAC:
  1. Go to the Auth0 Dashboard → Applications > APIs → your API → Permissions
  2. Add the permissions your application needs (e.g., admin:dashboard, read:messages)
  3. Go to User Management > Roles, create a role, and assign permissions to it
  4. Assign the role to users from their profile page
See Role-Based Access Control for the full guide.

​
Next Steps

Now that you have authentication working in your Laravel application, explore more Auth0 features: