- How do I install and configure birdcar/authkit-laravel?
- Install it with Composer via composer require birdcar/authkit-laravel, then publish the package config and set your WorkOS credentials (API key, client ID, and redirect URL) in your .env file. The package registers a Laravel guard and service-provider bindings over the official workos/workos-php SDK, so there is no separate identity service to run. Because it is a thin adapter, most configuration lives in WorkOS itself rather than in Laravel config files.
- Which Laravel and PHP versions does birdcar/authkit-laravel support?
- The package is a thin adapter over the official workos/workos-php SDK and targets modern Laravel applications. Version 2.1.0 fixed compatibility with workos/workos-php 9.2.0, which acts as a practical floor, so projects pinned to older SDK releases cannot take this update. Check the composer.json constraints for the exact Laravel and PHP matrix before upgrading.
- How do I test WorkOS authentication in Laravel without a live WorkOS tenant?
- Use Authkit::fake(), which is the headline feature of v2.1.0 and provides fakes for FGA, Invitations, Audit Logs, org sync, API keys, Vault, Pipes, and Groups. This replaces the old approach of mocking the WorkOS SDK by hand or skipping auth tests entirely, so you can enforce a real quality gate in CI. Fakes are designed to stay faithful to the real contracts, but treat that fidelity as a maintained assumption and add regression tests around the behaviors you depend on.
- What is the difference between Authkit::fake() and Authkit::actingAs()?
- Authkit::fake() swaps out the WorkOS-backed managers for in-memory fakes so calls do not hit the network, while Authkit::actingAs() authenticates a given user through the package's real guard machinery for the duration of a test. Authkit::actingAsGuest() covers the unauthenticated path. Typically you call fake() to stub WorkOS services and actingAs() to set the logged-in user, then assert as usual.
- Can I fake only some WorkOS services and keep the rest real?
- Yes. Fakes are selective: calling Authkit::fake(['fga', 'vault']) fakes only those managers and leaves everything else on the real code paths. This mixed-mode approach is useful for integration tests that need genuine behavior from one WorkOS service while stubbing another. Just be explicit in test setup so it is obvious which managers are simulated and which are live.
- Why are my WorkOS requests suddenly going through Laravel's HTTP client, and how do I switch back to Guzzle?
- In v2.1.0 the authkit.http.transport option defaults to laravel, so WorkOS traffic flows through Laravel's HTTP client instead of Guzzle directly. That gives you observability and policy enforcement via global HTTP middleware and Http:: events, but it also means your global middleware now sees authentication requests. Set AUTHKIT_HTTP_TRANSPORT=guzzle to restore the previous behavior, and audit body logging, header injection, and timeout or retry settings before leaving the default on in production.
- Does birdcar/authkit-laravel support SSO, Directory Sync, FGA, Vault, and Audit Logs?
- Yes. The package exposes WorkOS features including SSO, Directory Sync, Fine-Grained Authorization, Vault, Audit Logs, Pipes, Groups, and API keys as Laravel-friendly managers behind the guard. Each of these has a corresponding fake in v2.1.0, so they can be exercised in tests without a WorkOS tenant. It is intended for teams already standardizing on WorkOS for enterprise identity rather than for rolling your own identity provider.
- How does it compare to Laravel Socialite, Fortify, or using the WorkOS SDK directly?
- Socialite and Fortify solve local or social login flows, whereas this package is an opinionated adapter for WorkOS enterprise identity, so they address different problems. If you want maximum control or only a narrow WorkOS feature, calling workos/workos-php directly is perfectly reasonable and avoids an extra abstraction. Choose authkit-laravel when you want a Laravel guard, service-provider bindings, and test fakes out of the box.
- What breaking changes or migration steps come with v2.1.0?
- No migration steps are mandated. The realistic work is bumping the workos/workos-php pin to 9.2.0, auditing global HTTP middleware and Http:: event listeners now that WorkOS traffic traverses them by default, and retiring bespoke test scaffolding in favor of Authkit::fake(). Two behavioral notes: seven previously-final manager classes are now subclassable, and assertions made without a prior fake() now throw a LogicException instead of a fatal undefined-method error.
- Is birdcar/authkit-laravel production-ready, and what risks should I watch?
- For Laravel applications already using WorkOS, the architecture is sound: a thin guard and service-provider layer over the official SDK, with no separate identity service to operate. The main risks are fake/real divergence as the WorkOS SDK evolves, credentials or tokens leaking into logs if global HTTP body logging is enabled now that the Laravel transport is the default, and a buggy global middleware being able to break authentication. Also note that Http::preventStrayRequests() will surface latent unmocked WorkOS calls in one burst, which is desirable but disruptive if adopted late.