Client Php Laravel Package

Getting Started

Treat this package as a vendor SDK for an existing Corbado/passkey integration, not a general-purpose auth package. It is archived, so pin the version and isolate it behind your own interface before building on it.

1. Install and confirm the PHP/extension constraints:

   composer require corbado/client-php
   

2. Put Corbado credentials in config/services.php, not directly in code:

   'corbado' => [
       'project_id' => env('CORBADO_PROJECT_ID'),
       'api_secret' => env('CORBADO_API_SECRET'),
   ],
   

3. Read the package README first, then src/Client.php and the exception classes. The important surface is usually: construct a client with project ID/API secret, then call resource accessors such as sessions(), users(), identifiers(), and passkeys().
4. Bind the SDK client as a singleton in a service provider:

   $this->app->singleton(\Corbado\Client::class, function () {
       return new \Corbado\Client(
           projectId: config('services.corbado.project_id'),
           apiSecret: config('services.corbado.api_secret'),
       );
   });
   

   Check the README for the exact constructor signature in your pinned release.
5. First use case: verify a Corbado session token from the frontend and turn it into a Laravel identity:

   $session = app(\Corbado\Client::class)
       ->sessions()
       ->verify($request->bearerToken());
   
   $user = User::firstOrCreate(
       ['corbado_user_id' => $session->userID],
       ['name' => $session->userName ?? 'Passkey user'],
   );
   
   Auth::login($user);
   

Do not expect this package to render passkey UI. Corbado’s frontend component/API handles registration and login; this SDK is the backend verification and management layer.

Implementation Patterns

Middleware-based session verification Centralize token verification in middleware rather than repeating it in controllers. Attach the verified session to the request:

$request->attributes->set('corbado_session', $session);

Then resolve your local user from corbado_user_id. This keeps your controllers free of SDK calls and makes it easy to swap the SDK later.

Frontend-to-backend exchange Typical flow:

1. Frontend uses Corbado’s web component/frontend API to register or authenticate with a passkey.
2. Frontend receives a short-lived Corbado session token.
3. Frontend sends it to Laravel as a bearer token or in a dedicated header.
4. Laravel verifies it with sessions()->verify(...).
5. Laravel issues its own session/Sanctum token and logs the user in.

Do not store the Corbado token as your long-lived application session. Exchange it once.

Local user mapping Add a nullable, unique corbado_user_id to your users table. Resolve users by that ID, not by email, because identifiers can change. For first login, use a transaction or firstOrCreate to avoid duplicate users under concurrent requests.

Backend administration Use the SDK for account management screens or Artisan commands:

• list a user’s passkeys and identifiers;
• delete a compromised passkey;
• inspect user metadata;
• remove a user during GDPR/account deletion.

Wrap these calls in small service methods such as CorbadoAccountService::deletePasskey($userId, $passkeyId) so controllers do not depend directly on SDK response shapes.

Laravel integration tips

• Bind the client in AppServiceProvider or a dedicated CorbadoServiceProvider.
• Use constructor injection in services, not app() calls inside domain code.
• Keep Corbado calls out of model observers and queued jobs unless you add retries and idempotency.
• If you support multiple Corbado projects, create separate client instances keyed by environment; never share test and production secrets.
• For APIs, return 401 when session verification fails and 503 when Corbado is unreachable. Do not silently authenticate on network failure.

Testing Mock your own CorbadoGateway interface rather than mocking the SDK’s concrete client. Add one integration test against a Corbado test project for the real token-verification path.

Gotchas and Tips

• Archived package: No future security patches or PHP-version updates. Pin an exact minor version, run composer outdated, and plan to fork or replace it. If you are starting fresh, evaluate Corbado’s current SDK guidance or another passkey provider first.
• Constructor/config drift: The README is the source of truth. Confirm whether your pinned version expects named arguments, an array config, or an injected PSR-18 client before wiring the singleton.
• API secret exposure: CORBADO_API_SECRET is backend-only. Never expose it through Inertia props, VITE_ variables, JavaScript config, or logs. Rotate it in the Corbado dashboard if leaked.
• Laravel config caching: Use config('services.corbado.*') in providers. Calling env() after php artisan config:cache returns null.
• HTTP client dependencies: The SDK may rely on PSR-18/PSR-17 discovery. If Guzzle is not installed or discovery fails, inject a PSR-18 client explicitly. Set sensible connect/read timeouts; default timeouts can stall requests.
• Network call on every request: Session verification is a remote call. For high-traffic routes, consider a very short cache keyed by a hash of the token, with TTL shorter than token lifetime. Do not cache failed verifications, and fail closed on errors.
• Token lifetime and clock skew: Corbado session tokens are short-lived. Verify promptly and do not reuse them after exchanging for a Laravel session.
• Passkey origin constraints: Passkeys are bound to the relying party ID/domain. Changing your production domain, using a different subdomain, or misconfiguring localhost/HTTPS will break registration or login even if backend verification works.
• Error handling: Catch the SDK’s Corbado exception type and inspect the previous exception/response body in non-production. Distinguish invalid token (401) from Corbado outage (503), rate limiting (429), and misconfiguration (401/403 from Corbado with a valid-looking token).
• Debugging checklist: Confirm frontend project ID equals backend project ID; confirm the token is the Corbado session token, not a Corbado management API token; check the Corbado dashboard logs; log request IDs if the SDK exposes them.
• Do not trust client-supplied user IDs: Always derive the Corbado user ID from the verified session, never from a request body.
• Extension points: Put an interface such as CorbadoGateway around the SDK. Inject a logging PSR-18 client in non-production to see raw HTTP calls. If you need webhook handling or token introspection that the SDK does not provide, implement it separately and keep it outside the archived dependency.
• Composer conflicts: The SDK’s Guzzle/PSR versions may lag Laravel’s. If Composer cannot resolve, prefer injecting an existing compatible PSR-18 client over forcing a global downgrade.