Authkit Laravel Laravel Package

Technical Evaluation

Architecture fit

authkit-laravel sits between the application's auth layer and WorkOS (SSO, Directory Sync, FGA, Vault, Audit Logs, Pipes, Groups, API keys). Architecturally it is a thin, opinionated adapter: Laravel guard + service-provider bindings over the official workos/workos-php SDK. For any Laravel monolith or modular monolith already standardizing on WorkOS for enterprise identity, this is the intended shape — no separate identity service to operate.

v2.1.0 is primarily a testability and observability release, not a feature release. Its architectural significance is that it moves the package from "hard to test without a live WorkOS tenant" to "testable via the framework's native idioms." That materially changes the cost/benefit calculus for a TPM: the package now supports a real quality gate in CI rather than encouraging mocked-out or skipped auth tests.

The secondary architectural change — routing WorkOS traffic through Laravel's HTTP client by default — pulls an external dependency into the application's outbound-request governance layer. This is a net positive for observability and policy enforcement, but it is a default-on behavior change that interacts with whatever global HTTP middleware the application already runs.

Integration feasibility

High for greenfield and for existing consumers. The release is additive plus one default flip:

• New: Authkit::actingAs(), Authkit::actingAsGuest(), Authkit::fake() with fakes for FGA, Invitations, Audit Logs, org sync, API keys, Vault, Pipes, and Groups. Fakes are selective — Authkit::fake(['fga', 'vault']) leaves other managers on real code paths, enabling mixed-mode integration tests.
• Changed: previously-final manager classes are now subclassable for testing, guarded by an arch test. Low risk to consumers; widens the extension surface.
• Changed: authkit.http.transport defaults to laravel; AUTHKIT_HTTP_TRANSPORT=guzzle is the documented escape hatch.
• Fixed: workos/workos-php 9.2.0 compatibility (events poller now passes the required $events filter explicitly).

No migration steps are mandated. The realistic work is (a) bumping the WorkOS SDK pin, (b) auditing global HTTP middleware and Http:: event listeners for what they will now see, and (c) retiring bespoke test scaffolding.

Technical risk

• Fake/real divergence (highest). The entire value proposition rests on fakes being faithful to the real contracts. Vault's optimistic-locking ConflictException, the authkit-key guard authenticating fake keys "through its real machinery," and FGA cache-bust behavior are all called out as deliberately preserved — which signals the maintainers know this is the failure mode. Still, drift is inevitable across WorkOS SDK versions. Treat fake fidelity as a maintained contract needing its own regression tests, not a one-time deliverable.
• Transport default flip. WorkOS requests will now traverse application-global HTTP middleware and fire HTTP client events. Risks: credentials or tokens appearing in logs/traces if body logging is enabled globally, unexpected header injection, altered timeout/retry semantics, and a new failure surface where a buggy global middleware can break authentication in production.
• Http::preventStrayRequests() fallout. Teams that adopt this idiom will find previously-silent unmocked WorkOS calls now fail tests. Desirable, but it will surface latent test debt in one burst.
• Widened inheritance surface. Removing final from seven managers creates implicit extension points; consumers may subclass assumptions the maintainers never intended to support.
• SDK coupling. The 9.2.0 fix is a hard-ish floor. Teams pinned to older workos-php cannot take this release.
• Behavioral assertion change. Assertions without a prior fake() now throw a LogicException rather than an undefined-method fatal — better DX, but a behavior change for anyone (unlikely) depending on the old failure.

Key questions

1. What is the fake-fidelity guarantee? Is there a contract test suite run against the real SDK, and how is drift caught across workos-php releases?
2. Is the guzzle transport a permanent supported opt-out or a deprecation path toward Laravel-only?
3. What is the support matrix — Laravel versions, PHP versions, workos-php range — and the semver policy for the newly non-final managers?
4. Does the Laravel HTTP transport preserve SDK retry, backoff, and JWKS-cache semantics exactly, or only "unchanged" by inspection?
5. What is the recommended posture on global HTTP middleware now that auth traffic is in scope — do the docs call out PII/token redaction explicitly?
6. Does actingAs cover impersonation + organization + permission combinations well enough to replace our existing auth test helpers, or is it additive?

Integration Approach

Stack fit

Native Laravel/PHP. The testing surface deliberately mirrors framework conventions (actingAs, Http::fake, Http::assertSent, Pest-first docs), so it composes with existing test suites rather than introducing a parallel testing dialect. For teams already on Pest and Laravel's HTTP client fakes, adoption is close to zero-friction.

Migration path

Incremental and reversible at each step:

1. Pin workos/workos-php to >=9.2.0; upgrade the package. Verify the events poller still behaves (empty $events = all types, same wire request).
2. Run the existing suite unchanged — the transport default flip is the only thing that can surprise you. If global middleware interferes, set AUTHKIT_HTTP_TRANSPORT=guzzle as a short-term stabilizer and fix forward.
3. Adopt Authkit::actingAs() / actingAsGuest() first; they replace the largest block of brittle auth setup with the smallest conceptual leap.
4. Adopt fakes per manager, in order of test pain: Audit Logs and Invitations first (assertion APIs), then FGA, then Vault and Pipes where the exception parity matters.
5. Turn on Http::preventStrayRequests() last, once fakes cover the surfaces in use.

Compatibility

Requires workos-php 9.2.0+; older pins must be upgraded. Config additions: authkit.http.transport (default laravel). Config cache must be rebuilt. Fakes assume the package's own manager bindings; apps that have rebound or decorated these managers in their service provider need to verify Authkit::fake() still swaps the right instance.

Sequencing

Ship the SDK bump and transport audit as one low-risk change (no test changes), then land actingAs adoption, then per-manager fakes, then stray-request enforcement. Keep the guzzle opt-out documented in the runbook as the rollback lever for the transport change. Budget review time for global middleware owners — this is a cross-team change even though it lands in one dependency bump.

Operational Impact

Maintenance

Ongoing cost is low but not zero. Two new maintenance obligations: keeping fakes aligned with workos-php upgrades (the package maintainers own this, but pin your upgrade cadence to it), and governing the HTTP transport — any change to global outbound middleware now has an auth blast radius and should require review from the team owning identity.

Support

Support load should drop. The LogicException-with-a-fix-name pattern replaces a class of confusing fatal errors with actionable messages, and docs/testing.md gives a single canonical answer to "how do I test this?" That is the single biggest lever for reducing internal support pings on auth.

Scaling

Neutral to positive. Fakes are in-memory; no network in tests means CI runtime and flake rate both improve as auth coverage grows. In production, routing through Laravel's HTTP client adds a thin middleware layer per WorkOS call — negligible against network latency, but it does mean WorkOS retry storms and timeouts are observable in your existing HTTP metrics rather than invisible. That is a scaling win: auth is no longer a blind spot in capacity dashboards.

Failure modes

• Fake passes, production fails (drift). Mitigate with a small smoke suite against a real WorkOS test tenant, run on a schedule rather than per-PR.
• Global HTTP middleware leaks tokens into logs. Mitigate with a redaction audit before enabling the default transport.
• preventStrayRequests() breaks unrelated tests. Mitigate by sequencing it last.
• SDK pin mismatch breaks the events poller. Mitigate by treating the workos-php constraint as a tracked dependency, not a floating range.
• Subclassing non-final managers in app code and then hitting an upstream refactor. Mitigate with a policy: do not subclass; use Authkit::fake() and the documented seams.

Ramp-up

Genuinely short. A Laravel developer with Pest experience can be productive with actingAs in under an hour and with manager fakes in under a day, using docs/testing.md as the sole reference. The ramp-up cost is concentrated in one place: whoever owns HTTP middleware and observability needs to understand that WorkOS traffic is now in their domain. That is a one-hour conversation, not a training program — but it must happen before the transport default reaches production.