Authkit Laravel Laravel Package

Product Decisions This Supports

• Test strategy and CI economics: Authkit::actingAs(), actingAsGuest(), and Authkit::fake() make WorkOS-backed auth a fully offline, in-process concern in Pest/PHPUnit. A PM can now justify shipping SSO, SCIM/org sync, FGA, Vault, Audit Logs, invitations, API keys, Pipes, and Groups without carving out a paid third-party sandbox or a staging tenant in every CI run — directly reducing flaky builds, test runtime, and per-seat WorkOS sandbox costs.
• Build vs. buy on auth infrastructure: Because every wrapped WorkOS surface (FGA, Vault, audit logs, invitations, org sync, API keys, Pipes, Groups) can be scripted and asserted in-memory, "buy WorkOS + Authkit" no longer implies a testing tax that a homegrown auth stack would avoid. This tilts build-vs-buy evaluations toward buy, and is a concrete counterargument in technical due diligence.
• Enterprise-readiness claims on the roadmap: The package now credibly supports the compliance-flavored features PMs sell into enterprise deals — audit log assertions (AuditLog::assertLogged(...) with real actor resolution and metadata sanitization), impersonation with the Impersonating event, org-scoped API keys, and Vault optimistic-locking ConflictException parity. These become testable acceptance criteria rather than promises, so "audit logging," "impersonation," and "secrets rotation" can move onto a roadmap with confidence.
• Feature parity with real auth semantics: Claims flow through the same contracts the real guard uses, so Gate checks, Authkit::currentOrganization(), $request->organization(), and the Pennant workos store behave identically to live login. That means PMs can sign off on authorization and feature-flag behavior in unit tests rather than manual QA passes.
• Partial-fake adoption path: Authkit::fake(['fga', 'vault']) keeps unfaked managers on real code paths, so teams can adopt incrementally — useful when sequencing a migration across squads rather than mandating a big-bang test rewrite.
• Observability and platform standards: Routing WorkOS traffic through Laravel's HTTP client (authkit.http.transport, default laravel) means Http::preventStrayRequests(), Http::fake(), and Http::assertSent() work as expected, and production HTTP middleware/client events observe WorkOS calls like any other outbound request. That's a platform-consistency win PMs can point to when defending a "no special-case SDKs" architecture policy.

When to Consider This Package

Consider it when:

• You are on Laravel and standardizing on WorkOS for SSO/Directory Sync, and you want first-party-feeling ergonomics rather than hand-rolling SDK glue.
• Test coverage of auth-adjacent flows is a gating concern — i.e., you need offline, deterministic tests for FGA, Vault, audit logs, invitations, org sync, API keys, Pipes, or Groups, and you don't want to maintain a fake WorkOS tenant.
• You rely on Laravel idioms (Gate, Pennant, HTTP client fakes, Http::preventStrayRequests()) and want WorkOS to behave like the rest of the framework.
• You need enterprise-flavored behaviors (impersonation, audit trails, secrets versioning) to be verifiable in CI before you commit them to customers.
• Your release process relies on catching auth regressions at the unit level rather than via staging or manual QA.

Look elsewhere when:

• You are not on Laravel, or you're on a PHP framework where the guard/manager contracts here don't map cleanly.
• You deliberately want thin, unopinionated SDK access and would rather own the abstraction layer yourself.
• You're pinned below workos/workos-php 9.2.0 with no upgrade path, or you require the guzzle transport for existing middleware/telemetry reasons and don't want a configuration seam. (Both are supported — AUTHKIT_HTTP_TRANSPORT=guzzle opts out — but they add a decision to make.)
• You need a stable, frozen testing API and cannot absorb subclassing changes: manager classes that gained fakes are no longer final, and testing assertions now throw LogicException when called without faking first. That's a better failure mode, but it is a behavioral change for any test suite that relied on the previous undefined-method fatal or on final semantics.

How to Pitch It (Stakeholders)

For executives: v2.1.0 closes the last real gap in buying auth instead of building it. Until now, adopting WorkOS meant our test suite either hit a live sandbox or skipped auth paths entirely — slow, flaky, and a recurring line item. With Authkit::fake() and actingAs(), every WorkOS surface we wrap is now testable offline in milliseconds, with no credentials and no network. Practically: faster CI, fewer escaped auth bugs, lower sandbox spend, and the ability to put audit logging, impersonation, and secrets management on the roadmap as verifiable commitments rather than aspirations.

For engineering: This is a testing release, and it's the one you'd have written. Authkit::actingAs($user, [...]) and actingAsGuest() inject synthetic workos sessions with no cookie, no JWKS fetch, and no SDK call — but claims flow through the exact contracts the real guard uses, so Gate, Authkit::currentOrganization(), $request->organization(), and the Pennant workos store all behave as they would in production. Authkit::fake() swaps manager bindings for typed in-memory fakes with scripting and assertions: FGA allow/deny with assertChecked, a stateful invitation registry, AuditLog::assertLogged(...) with real actor resolution and metadata sanitization, org-sync Bus capture plus completeSync(), user- and org-scoped API keys that authenticate through the real authkit-key guard machinery, a Vault KV store with version history and ConflictException parity (with the Vaulted cast and vault disk running real code paths over clearly-marked fake crypto), Pipes fixtures and scripted tokens with both business exceptions triggerable, and full Groups CRUD/membership/roles with the FGA cache-bust contract intact. Faking is opt-in per manager — Authkit::fake(['fga', 'vault']) leaves everything else live — so adoption can be incremental. Separately, WorkOS traffic now rides Laravel's HTTP client by default (authkit.http.transport, default laravel; guzzle to opt out), so Http::preventStrayRequests(), Http::fake(), and Http::assertSent() finally see these calls, and production middleware and HTTP client events observe them like any other outbound request. SDK retry, error-mapping, and JWKS caching are unchanged.

Two things to note before upgrading: manager classes that gained fakes are no longer final — each has a designed testing subclass guarded by an arch test, so any local subclassing assumptions should be re-checked. And calling a testing assertion without faking first now throws a LogicException naming the fix, instead of an undefined-method fatal; that's strictly better, but it will surface in any suite that was silently doing the wrong thing. We've also fixed compatibility with workos/workos-php 9.2.0, where the events poller now passes the required $events filter explicitly (empty = all types, same wire request as before) — worth pinning deliberately. Full guide: docs/testing.md.