Client Laravel Package

Technical Evaluation

Architecture fit. ory/client is an OpenAPI-generated SDK, not a framework integration. It gives you typed API classes against Ory's headless identity stack (Kratos for identity, Hydra for OAuth2/OIDC, Keto for permissions, Oathkeeper for proxying) and nothing else — no service provider, no config, no facade, no container bindings, no Eloquent mapping. In a Laravel app it therefore occupies the infrastructure adapter layer, sitting beside Auth rather than replacing it. Fit at the HTTP/JSON boundary is good; fit at the framework layer is essentially zero and must be built.

Integration feasibility. Straightforward mechanically: composer require ory/client, instantiate the generated Configuration, bind API classes as singletons. Realistic effort is a 1–2 sprint slice for a senior dev: config + provider + facade, an anti-corruption interface (IdentityProvider, SessionValidator, PermissionChecker), DTO mapping between Ory identities and Eloquent users, and translation of generic ApiExceptions into domain exceptions. The hard part is not code volume (~500–1500 LOC) — it is Ory's flow semantics: browser-redirect self-service flows with CSRF tokens that must interoperate with Laravel's own session and CSRF middleware.

Technical risk.

• Ecosystem validation is effectively absent. 7 stars, 0 dependents, composite score 0.165. There is no Stack Overflow corpus, no reference implementations to crib from, and no community to absorb upgrade pain. Generated code quality may be fine; the support surface is not.
• Generated-code churn. The client is regenerated per Ory API release. Model and method names shift between minor versions (credential/identity model renames are common in OpenAPI generators), and the PHP client's semver does not reliably track behavioral compatibility.
• Auth is a single point of failure. Any adoption makes Ory a hard runtime dependency for login, signup, and permission checks; an Ory outage is a product outage.
• Session topology. Kratos issues its own session cookie; making that authoritative alongside Laravel's session requires same-parent-domain deployment or a switch to bearer/JWT validation with JWKS caching.
• Error surfaces. Ory returns structured {"error": {"id": ..., "message": ...}} payloads; the generated client throws an opaque ApiException with the raw body, so every call site needs mapping.
• Deployment ambiguity. Ory Network vs. self-hosted changes endpoints, TLS, rate limits, and upgrade responsibility.

Key questions.

1. Which Ory products are actually in scope, and is this Ory Network or self-hosted (affects endpoint config, support, and data residency)?
2. Does the generated client at our pinned version expose the endpoints we need (verify against the tag list, not the docs)?
3. Session model: is the Kratos session cookie authoritative, or do we exchange it for a Laravel session on each request? What is the JWKS rotation strategy?
4. How is identity.id mapped onto the existing users table — dual-write, webhook-driven sync, or full re-platform onto Ory as source of truth?
5. Has anyone evaluated whether Laravel-native (Sanctum + Passport + Socialite) already covers 80% of the requirement at a fraction of the operational cost?
6. Who owns the wrapper layer and the Ory upgrade cadence after launch?

Integration Approach

Stack fit. Laravel 10/11, PHP 8.1+. Bind the generated API classes behind our own interfaces in a dedicated OryServiceProvider; publish config/ory.php driven by env (ORY_ENDPOINT, ORY_PROJECT_SLUG, ORY_API_KEY or bearer token, per-product base URLs for self-hosting). Offer a thin facade for ergonomics but inject the interface into controllers so the generated types never leak into domain code. Use Laravel's HTTP client only for health checks and webhook ingestion; all API traffic goes through the SDK to keep one serialization path.

Migration path. Do not lift-and-shift authentication.

• Phase 0 — Spike (1 week). Clone the repo, install, point at a throwaway Kratos project, exercise the exact endpoints we intend to use, and capture real error bodies. Kill the initiative here if coverage is thin.
• Phase 1 — Adapter. Config, provider, interfaces, exception mapping, and contract tests against a pinned oryd/kratos Docker image in CI.
• Phase 2 — Bounded parallel run. One narrow surface only: staff/admin login with MFA, or a new B2B tenant portal. Never migrate the primary consumer login first.
• Phase 3 — Identity sync. Webhook receiver (identity.created/updated/deleted) with idempotent upsert into users, plus a nightly reconciliation job for dropped deliveries.
• Phase 4 — Feature-flagged cutover of remaining flows, with the legacy path kept warm for one release cycle.
• Phase 5 — Decommission legacy auth code and drop unused packages.

Compatibility. Pin the exact SDK version and lock the Ory API version in an ADR; treat SDK upgrades as planned work with contract tests, never as composer update noise. Check Guzzle/PSR-7/PSR-18 constraint conflicts against anything else pinning guzzlehttp/guzzle (AWS SDK, Flysystem adapters, mail transports). If Kratos is deployed on a different registrable domain than the app, plan for bearer-token sessions instead of cookie-based ones — that decision cascades into middleware and tests.

Sequencing. Identity schema design → adapter layer + contract tests → webhook sync → UI flow wiring (Blade/Inertia/Livewire) → session bridge → permissions (Keto, only if needed) → observability → rollout. Front-load schema design; changing it after users exist means migration scripts in Ory, which is materially harder than an Eloquent migration.

Operational Impact

Maintenance. You permanently own the wrapper layer. Budget ~0.1–0.25 FTE for SDK/API upgrades, contract-test upkeep, and Ory version chasing. Generated code is not something you patch — pin it, or fork it if you must deviate.

Support. Effectively self-support. No community, no dependents to learn from, no vendor-neutral troubleshooting corpus. Recourse is Ory's documentation, their Discord/GitHub, and — if on Ory Network or Enterprise — a commercial support contract that should be priced into the decision. Apache-2.0 is clean for commercial use; run a standard supply-chain review on the generated code and its transitive HTTP deps.

Scaling. The client is stateless and cheap; throughput is bounded by the Ory deployment (Kratos/Hydra databases) and per-request network RTT. Two patterns to enforce: cache validated sessions and JWKS locally with short TTLs, and never resolve the identity from Ory more than once per request — stash it in the Laravel session or Redis. Watch for accidental N+1 API calls in middleware and policies.

Failure modes.

• Ory unreachable → login, signup, and permission checks fail. Need a circuit breaker, cached-identity degradation for read paths, and a documented break-glass admin route.
• Key rotation → stale JWKS produces mass 401s; refresh on kid miss rather than on a timer alone.
• Webhook loss → silent drift between Ory and users; mitigate with reconciliation and alerting on sync lag.
• SDK/API version skew → 400/404 on renamed endpoints after an upgrade; contract tests are the only reliable detector.
• 429 rate limiting → retry with jittered backoff and push non-critical calls (courier resends, audit enrichment) onto the queue.

Ramp-up. The SDK itself is learnable in a day. Ory's conceptual model — identity schemas, self-service flow state machines, courier templates, session semantics, credential types — is the real ramp: roughly 1–2 weeks for a senior engineer before they are productive, more for whoever owns the deployment. Write an ADR and a one-page onboarding doc before committing, and be explicit that choosing this package means choosing Ory's model, not just an HTTP library.