Workos Php Laravel Package

Product Decisions This Supports

• Group-Based RBAC — the enterprise unlock in v9.5.0:

  • New UserRoleAssignmentSourceGroup model and group on UserRoleAssignmentSource mean role assignments can now be attributed to an IdP/directory group, not just an individual membership. This is the difference between "we support SSO" and "our customers' IT teams can govern our app's permissions from their directory."
  • Decision this supports: whether to build in-house group→role mapping (weeks of work, permanently stale) or inherit it from the identity layer. Inherit. This also moves us from seat-by-seat permission administration to self-serve enterprise onboarding — a real procurement blocker removed.
  • Roadmap implication: group-based assignment plus directory sync groups means we should stop designing any admin UI that assumes per-user role editing is the primary path. Design for "roles flow from groups, overrides are the exception."

• Pipes: Connected Accounts Are Now Identifiable, Attributable, and Diagnosable (direct follow-through on last release's multi-connection work):

  • account_display_name / account_identifier on every connected-account request/response model (organization, user, data-integration API-key and upsert variants alike). Last release gave us AccountSelectionRequiredError — the hook for an account picker. This release gives us the content to render in it: "Acme Salesforce — [email protected]." The account-selection UX is now buildable end-to-end. Ship it; it was previously a half-feature.
  • established_by_user_id on ConnectedAccount and ConnectedAccountWriteResponse gives us attribution: who connected this account. Enables offboarding ("revoke integrations established by a departing user" — a security questionnaire favorite), per-seat/agency billing justification, and audit trails without our own join table.
  • state_reason turns silent broken integrations into actionable product states. We can drive proactive "reconnect your X account" prompts and health dashboards instead of waiting for a user to hit a failure. This is a retention feature, not plumbing.
  • ConnectedAccountWriteResponseWarning lets us surface partial success ("connected, but here's what didn't work") rather than a binary pass/fail. Design the UI to accept warnings as a first-class outcome.
  • Decision this supports: integrations is now a supportable product surface with identity, ownership, attribution, and health — not just a connection store. Budget UI work here; the SDK no longer blocks it.

• ⚠️ Breaking: Pipes Request Models Removed + Idempotency Contract Changed (roadmap risk — schedule, don't absorb opportunistically):

  • Removed: AddDataIntegrationsUpsertApiKeyRequest, AddDataIntegrationsUpsertClientCredentialsRequest, and their ...ConnectionOwner enums. Any code constructing these for API-key or client-credential upserts will not compile. Migration is to the surviving DataIntegrationsUpsertApiKeyRequest (and ...Request2) shapes — but note ownership/connection_owner typing has shifted, so the ownership modeling we adopted last release needs re-verification.
  • Idempotency-key contract changed on POST /data-integrations/{slug}/api-key, .../client-credentials, POST /organizations/{org}/connected_accounts/{slug}, and POST /user_management/users/{user}/connected_accounts/{slug} — precisely the "connect an account" write paths. Engineering must confirm retry/duplicate behavior before we ship anything with automatic retries. Product risk: a flaky-network retry in onboarding could create duplicate connections or fail silently.
  • PM action: treat this as a scoped migration ticket with an audit window, not a drive-by upgrade. It is the one item in this release that can break a working flow.

• Admin Portal: Self-Serve Revocation and Pre-Provisioned Links:

  • New POST /portal/revoke_link + RevokeLink model = IT admins can revoke access without a support ticket. Measurable impact on support load and on our deprovisioning SLA story.
  • external_user_id on GenerateLink means we can mint portal links for users before they exist in WorkOS — invited-but-not-yet-signed-up, or pre-provisioned seats. Unlocks "invite your admin and let them configure SSO themselves" onboarding, instead of a white-glove implementation call.
  • Decision this supports: whether enterprise onboarding is sales-assisted or self-serve. The SDK now supports self-serve; whether we invest in the funnel is a product choice, but the excuse is gone.
  • Note: generate_link error responses changed — our error-message mapping for that endpoint needs a pass.

• Directory Sync: On-Demand Sync Changes the Deprovisioning Story:

  • POST /directories/{id}/sync with DirectorySyncResponse gives us a "Sync now" action in admin settings, plus a way to force a reconcile after a customer's IdP change. New DirectorySyncRateLimitError means we can handle throttling explicitly rather than with a generic failure and a retry storm.
  • Decision this supports: committing to a deprovisioning SLA in enterprise contracts (e.g. "access removed within N minutes of IdP removal") instead of "up to the next sync cycle." Combined with group-based role assignment, this is a coherent enterprise governance story.

• Agents: invocable_as — the Build-vs-Buy Hold Just Got Stronger:

  • AgentBlueprintInvocableAs plus ...InvocableAsInstanceTypes enums on create/update/read models means agent invocation identity and scope are now modeled by the vendor. Last release was a signal; this is a schema.
  • Decision this supports: keep holding on in-house agent auth for 2–4 quarters. If agentic features are on the roadmap, we ride the vendor's model rather than inventing an identity scheme we'd have to migrate off.

• Cross-Cutting: Mass "Changed errors" Across Audit Logs, FGA/Authorization, Feature Flags, Organizations, Organization Membership:

  • Every listed endpoint's error contract changed — typed error classes and/or response shapes for audit log actions/schemas/exports/events, all FGA resource and role-assignment endpoints, feature-flag enable/disable, audit-log retention, and IT-contact invites.
  • Product consequence: any UI that maps error conditions to human-readable messages or recovery paths (especially FGA permission failures and audit-log export failures) may now fall through to a generic error. This is a UX-regression risk in admin/compliance screens that will not show up as a test failure.
  • Decision this supports: fund a small error-mapping audit as part of the upgrade, and add a rule that we never branch on raw error strings for these surfaces.

• Carried forward from v9.4.0 (still the security baseline):

  • Issuer-validated sessions (SessionManager::authenticate() optional issuer check) — enabler for multi-tenant/white-label SSO; map tenant routing to expected issuer.
  • Mandatory JWT expiration — decide legacy-token remediation before adoption.
  • Passwordless/magic-link URL-encoding fix — commit to passwordless as a supported onboarding path.
  • Value-format changes on API key value, MFA code/secret/qr_code/uri, SSO key, Vault secrets, MagicAuth.code, PortalLinkResponse.link, reset/verification URLs — still an open audit item if not yet completed.

When to Consider This Package

Adopt (or upgrade to) This Package If:

• You are already on v9.4.x and want the account-selection UX made real (account_display_name/account_identifier), connection attribution (established_by_user_id), connection health (state_reason), and partial-success handling (ConnectedAccountWriteResponseWarning).
• You sell to enterprises whose security teams demand group-driven permissions and a provable deprovisioning story — UserRoleAssignmentSourceGroup + POST /directories/{id}/sync are exactly those answers.
• You want IT-admin self-service for SSO setup and access revocation (GenerateLink with external_user_id, POST /portal/revoke_link) rather than white-glove implementation calls.
• You run more than one issuer (staging + prod, white-label tenants, multi-brand) and need issuer-validated sessions with enforced JWT expiration (v9.4.0 baseline).
• You're shipping third-party data integrations and need per-org or per-user connected accounts, multiple connections per integration, and an account picker.
• You rely on passwordless/magic-link entry points at meaningful volume.
• You plan scoped OAuth resources for your own APIs (UserManagementAuthkitOAuthResources) or agent identity (AgentBlueprint.invocable_as).

Look Elsewhere If:

• You are mid-flight on a Pipes integration built on the removed AddDataIntegrationsUpsertApiKeyRequest / ...ClientCredentialsRequest models or on the old idempotency-key contract — finish or migrate deliberately; do not upgrade under release pressure.
• You cannot absorb a breaking model removal plus a retry-semantics change in your current cycle. Pin to v9.4.x and schedule v9.5.0 as its own ticket.
• You're not on PHP 8.2+ (unchanged constraint since v8.1.0).
• You don't use WorkOS's backend — the SDK is a thin, tightly coupled client; the Pipes/AuthKit/Agents models are WorkOS-shaped, not generic.
• You need static auth helpers — instantiated clients are still required.
• Your surface is simple username/password or single-tenant SSO with no connected accounts, no group-based RBAC, and no issuer validation. Value here is concentrated in multi-tenant, enterprise-governed, integration-heavy products.
• You have not yet completed the v9.4.0 token/secret/link format audit — stack the audits rather than interleaving them.

How to Pitch It (Stakeholders)

For Executives:

"v9.5.0 turns two things we said we 'supported' into things we can actually sell:

• Enterprise permission governance. Roles can now be sourced from directory groups, and admins can trigger an on-demand directory sync (with proper rate-limit handling) and revoke access themselves through the Admin Portal. That's the difference between passing a security review and being deferred to the next procurement cycle — group-driven access and a defensible deprovisioning window are checklist items we can now answer with 'yes' instead of 'roadmap.'
• Integrations become a real product. Connected accounts now carry a display name, identifier, who established them, and a reason when they're in a bad state. Last release gave us the account picker's trigger; this gives us the picker's contents and a health signal. That's retention and support-cost reduction, not plumbing.
• Admin self-service. Customers can now generate portal links for users who don't exist in our system yet and revoke access without a ticket — fewer implementation calls, lower support load per enterprise account.
• Agent identity is firming up (invocable_as schemas). Keep holding on building that ourselves; the vendor is doing it. Cost: one breaking change — two Pipes request models removed and the idempotency contract changed on the account-connection write paths — plus a re-verification of error handling across admin/compliance screens. Net: schedule a scoped migration ticket, take the enterprise unlocks. Still buy, don't build."

For Engineering:

"Upgrade to v9.5.0, but this one has a hard breaking change — treat it as a migration, not a bump. Four workstreams:

1. Pipes breaking migration (do this first). Removed: AddDataIntegrationsUpsertApiKeyRequest, AddDataIntegrationsUpsertClientCredentialsRequest, and their ...ConnectionOwner enums. Move to the surviving DataIntegrationsUpsertApiKeyRequest / ...Request2 shapes — and re-verify the ownership modeling from v9.4.0 (PipesOwnership / CreateDataIntegrationOwnership), since typing around connection_owner has shifted. Anything that compiled against the removed classes will not.
2. Idempotency contract changed on POST /data-integrations/{slug}/api-key, .../client-credentials, POST /organizations/{org}/connected_accounts/{slug}, and POST /user_management/users/{user}/connected_accounts/{slug}. Audit every retry path in the connect-an-account flow before shipping — confirm duplicate-creation behavior and failure modes. Do not assume last release's dedupe semantics.
3. Adopt the new Pipes fields: account_display_name, account_identifier on all create/read/response models; established_by_user_id and state_reason on ConnectedAccount / ConnectedAccountWriteResponse; handle ConnectedAccountWriteResponseWarning as a non-fatal outcome (partial success), and handle AccountSelectionRequiredError explicitly (carried from v9.4.0). New admin portal surface: RevokeLink + POST /portal/revoke_link, external_user_id on GenerateLink. New directory sync surface: POST /directories/{id}/sync, DirectorySyncResponse, and catch DirectorySyncRateLimitError specifically.
4. Error-contract re-verification (broad). 'Changed errors' landed on audit logs (actions, schemas, events, exports), nearly all FGA/authorization endpoints, feature flags, organizations (audit-log retention, IT-contact invite), and organization-membership delete. Walk every catch/mapping in admin and compliance code; stop branching on raw error strings. Then re-run the v9.4.0 format audit (API key values, MFA code/secret/QR/URI, SSO key, Vault values, MagicAuth.code, PortalLinkResponse.link, reset/verification URLs) if it isn't closed — grep for parsing, regex validation, truncation, and logging. New models to note: UserRoleAssignmentSourceGroup + group on UserRoleAssignmentSource; AgentBlueprintInvocableAs (+ create/update variants and instance-type enums) on invocable_as; DirectorySyncResponse. The Guzzle HTTP layer remains swappable; the changelog covers the migration path."

For Security/Compliance:

"v9.5.0 strengthens the governance controls auditors and enterprise security teams actually probe:

• Group-sourced role assignment (UserRoleAssignmentSourceGroup, group on UserRoleAssignmentSource) — permissions can be traced to an IdP group, which is what 'least privilege maintained from the system of record' means in practice.
• On-demand directory sync (POST /directories/{id}/sync) — lets us tighten the deprovisioning window from 'next scheduled cycle' to 'on demand,' which is a contract-level commitment we can now make.
• Admin-initiated revocation (POST /portal/revoke_link) — access removal no longer depends on a support workflow; it's auditable and immediate.
• Connection attribution (established_by_user_id) — we can identify and revoke integrations established by a departing or compromised user without maintaining a parallel ownership table.
• Connection health signal (state_reason) — degraded credentials become visible and remediable rather than silently persisting. Carried forward and still open: issuer validation on session authentication (cross-tenant token acceptance), mandatory JWT expiration, passwordless link integrity, short-lived tokens via max_age, explicit CORS/redirect URI whitelisting, and audit coverage via workos->auditLogs(). Two action items for us: (1) the mass error-contract changes across audit logs, FGA, feature flags, and organizations require a re-audit of our own error handling and user-facing failure messages — ensure failures in permission and audit-export paths don't degrade to generic errors that mask denials; (2) confirm the v9.4.0 secret-format audit is closed — API keys, MFA secrets/QR/URI, SSO key pairs, Vault values, and auth codes must not be logged, cached, or persisted in plaintext. The Pipes breaking change and idempotency-contract change are also worth a security review of retry paths: duplicate connections are a data-scoping risk, not just a UX bug."