Weave Code
Client Laravel Package
ory/client
A PHP client for integrating Ory identity and access APIs into Laravel applications, with generated SDK classes for services such as Kratos and Hydra. Useful for teams adopting Ory’s hosted or self-managed auth, though adoption and maintenance may be limited.
At a glance
Frequently asked questions about Client
- How do I install and configure ory/client in a Laravel application?
- Install it with composer require ory/client, then instantiate the generated Configuration class with your Ory endpoint and API key or bearer token. Because the package is a plain SDK, you wire it up yourself: publish a config/ory.php driven by env values such as ORY_ENDPOINT, ORY_PROJECT_SLUG and ORY_API_KEY, and bind the generated API classes as singletons in a small service provider. For self-hosted Ory you need per-product base URLs for Kratos, Hydra, Keto and Oathkeeper, since Ory Network and self-hosted deployments differ in endpoints, TLS and rate limits.
- Does ory/client ship a Laravel service provider, facade, or config file?
- No. ory/client is an OpenAPI-generated SDK, not a framework integration, so it contains no service provider, no config file, no facade and no container bindings. You must create the provider, config and optional facade yourself, plus an anti-corruption interface such as IdentityProvider or SessionValidator so generated types never leak into your domain code. Expect roughly 500 to 1500 lines of wrapper code for a production-ready integration.
- Which PHP and Laravel versions does ory/client support?
- The client is framework-agnostic PHP, so its constraint is the PHP version required by the generated code rather than Laravel itself. In practice teams run it on PHP 8.1+ with Laravel 10 or 11. Check the composer.json of the specific tag you pin, since the generated code is regenerated per Ory API release and requirements can shift between versions.
- What can I use ory/client for in a Laravel app — Kratos, Hydra, Keto?
- The SDK exposes generated service classes for Ory's headless identity stack: Kratos for identity and self-service login flows, Hydra for OAuth2 and OIDC, Keto for permission checks, and Oathkeeper for proxying. In a Laravel application it belongs in the infrastructure adapter layer, sitting beside Laravel's Auth rather than replacing it. You call the typed API classes for identity CRUD, session validation and permission lookups, then map the results into your own domain objects.
- How should I handle ApiException errors from Ory in Laravel?
- Ory returns structured payloads shaped like {"error": {"id": ..., "message": ...}}, but the generated client throws an opaque ApiException that carries the raw response body. Wrap every SDK call in a single adapter method that decodes the body and translates it into domain exceptions, so controllers and jobs never see the SDK's exception type. Doing this at one boundary instead of at each call site keeps error handling consistent and testable.
- Can I use the Kratos session cookie alongside Laravel's own session?
- Yes, but the session topology is the hard part of the integration. Kratos issues its own session cookie, so making it authoritative while Laravel also maintains a session requires deploying both on the same parent domain, or exchanging the Kratos session for a Laravel session on each request. The alternative is bearer or JWT validation using JWKS with a caching and rotation strategy, which avoids shared cookies but adds token handling to every request.
- How do I map Ory identities onto my existing Laravel users table?
- Add an identity_id column and map Ory identity payloads to Eloquent models through a dedicated DTO or anti-corruption layer rather than binding generated models directly. Choose deliberately between dual-write, webhook-driven sync, or re-platforming so Ory becomes the source of truth, because the choice drives every later migration. Do not lift-and-shift authentication; run a short spike against a throwaway Ory project first to confirm the flow semantics fit.
- How do I test Laravel code that calls ory/client?
- Because the SDK has no Laravel bindings, the practical approach is to depend on your own interfaces such as IdentityProvider or PermissionChecker and bind fake implementations in tests. That lets you assert behaviour without HTTP calls, and you confine SDK-specific tests to the adapter layer. If you must exercise the generated client, point its Configuration at a mocked endpoint via Laravel's HTTP fake or a local stub server.
- Is ory/client maintained and safe to use in production?
- Treat it with caution: the repository has very low adoption (around 7 stars and no dependents), so there is no Stack Overflow corpus, no reference implementations and no community to absorb upgrade pain. The client is regenerated per Ory API release, model and method names shift between minor versions, and its semver does not reliably track behavioural compatibility. Pin an exact version, wrap it behind your own interfaces, and assign clear ownership of the Ory upgrade cadence before launch, since any adoption makes Ory a hard runtime dependency for login and permission checks.
- Should I use ory/client or stick with Sanctum, Passport, and Socialite?
- Evaluate Laravel-native options first, because Sanctum, Passport and Socialite already cover a large share of typical authentication requirements at a fraction of the operational cost. ory/client only makes sense if you have deliberately adopted Ory's headless stack and need Kratos, Hydra or Keto features such as hosted flows, OAuth2 provider capabilities or fine-grained permissions. If Ory is already an organisational standard, the SDK is a reasonable HTTP boundary; if not, the wrapper effort and single point of failure are hard to justify.
Weaver
How can I help you explore Laravel packages today?