README

Drop-in WorkOS AuthKit integration for Laravel. Guards, middleware, Blade directives, Livewire widgets, webhook sync, and an interactive install wizard -- everything wired up so you can go from composer require to working authentication in about 15 minutes.

Installation

composer require birdcar/authkit-laravel

Run the install wizard:

php artisan workos:install

Add your WorkOS Dashboard credentials to .env:

WORKOS_API_KEY=sk_live_...
WORKOS_CLIENT_ID=client_...
WORKOS_REDIRECT_URI=https://your-app.test/auth/callback

The package auto-registers its service provider and WorkOS facade via Laravel's package discovery. See Installation for migration guides, custom guard names, and publishing config.

Quick start

The package registers a workos auth guard and sets up /auth/login, /auth/callback, and /auth/logout routes automatically:

// routes/web.php
Route::middleware('workos.auth')->group(function () {
    Route::get('/dashboard', fn () => view('dashboard'));
});

Check roles and permissions in routes or Blade:

Route::middleware(['workos.auth', 'workos.role:admin'])->group(/* ... */);
Route::middleware(['workos.auth', 'workos.permission:posts:write'])->group(/* ... */);

@workosRole('admin')
    <a href="/admin">Admin Panel</a>
@endworkosRole

@workosPermission('posts:write')
    <button>New Post</button>
@endworkosPermission

See Authentication and Authorization for the full API.

Testing

use WorkOS\AuthKit\Facades\WorkOS;

it('requires admin role', function () {
    $user = User::factory()->create();

    WorkOS::actingAs($user, roles: ['admin']);
    $this->get('/admin')->assertOk();

    WorkOS::actingAs($user, roles: ['member']);
    $this->get('/admin')->assertForbidden();
});

See Testing for WorkOS::fake(), builder methods, audit assertions, and the InteractsWithWorkOS trait.

Documentation

• Installation -- Setup, migration from existing auth, publishing config
• Authentication -- Guard, sessions, login/callback/logout, impersonation
• Authorization -- Roles, permissions, FGA, feature flags, middleware, Blade directives
• Organizations -- Multi-org, switching, invitations, domain verification
• Events & Webhooks -- Event routing, Events API polling worker
• Webhooks -- Real-time webhook ingestion, event handling, sync listeners
• Widgets -- Livewire components for user management, admin portal, etc.
• Testing -- WorkOS::fake(), actingAs(), assertions
• Audit Logging -- WorkOS Audit Logs integration
• Commands -- Artisan command reference
• Configuration -- Complete config reference

Requirements

• PHP 8.3+
• Laravel 11 or 12
• WorkOS PHP SDK ^5.0
• Livewire ^4.0 (optional, for widget components only)

License

MIT. See LICENSE for details.