birdcar/authkit-laravel

Laravel integration for WorkOS AuthKit

v1.0.0 2026-04-14 15:41 UTC

Requires

• php: ^8.3
• illuminate/contracts: ^11.0|^12.0|^13.0
• illuminate/support: ^11.0|^12.0|^13.0
• workos/workos-php: ^5.0

Requires (Dev)

• laravel/pint: ^1.0
• orchestra/testbench: ^9.0|^10.0|^11.0
• pestphp/pest: ^3.0
• phpstan/phpstan: ^2.0

Suggests

• livewire/livewire: Required for WorkOS Livewire widget components (^3.0)

MIT

• Authentication
• SSO
• laravel
• workos
• authkit

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.