ADR 0002: Clerk identity and Exo authorization boundaryCopy Anchor Link

• Status: superseded by 0003-convex-auth-v2-identity-plane.md
• Date: 2026-08-26

ContextCopy Anchor Link

Exo needs strong multi-tenant identity, organization membership, MFA, passkeys, session revocation, and future enterprise SSO. It must also avoid making a proprietary identity provider the canonical owner of tenant authorization or data identity.

DecisionCopy Anchor Link

Use Clerk as the target authentication provider for an environment-specific Exo identity plane. Exo-owned Apps share that plane so a person does not need a product-specific identity for each repository or domain. Map one Clerk user to one Exo ID within the plane and authenticate Clerk sessions through a Payload custom strategy or the App's Exo authorization adapter.

Exo remains responsible for authorization. Resource-local grants carry canonical scopes, roles, explicit capabilities, validity, and revocation state. Clerk Organizations may mirror coarse Workspace membership, but Organization membership is neither the canonical resource graph nor sufficient authorization.

Production and non-production use isolated identity planes. A separate identity plane for a client application's customers is allowed only when the application has an independently owned user population, legal boundary, or identity adapter. Another Exo-owned App does not qualify merely because it has a different repository or domain.

ConsequencesCopy Anchor Link

• Privileged users receive Clerk MFA, session management, recovery, and Organization context.
• Exo-owned Apps no longer provision separate Clerk identities per product.
• Exo must implement and test a custom Payload authentication strategy.
• Clerk webhooks are lifecycle synchronization, not synchronous authorization.
• The platform must maintain Exo identities, environment-specific external mappings, resource grants, account-linking safeguards, and audited revocation.
• Claims remain compact; resource authorization stays server-side.
• Privileged actions require recent factor verification and an audit event.
• Identity exports omit credentials and retain portable canonical user and membership IDs.
• A future provider adapter or self-hosted identity implementation remains possible.

Migration gateCopy Anchor Link

Payload local authentication remains active until Clerk staging proves:

1. account linking without duplicate or hijacked users;
2. production/non-production identity-plane isolation;
3. App, Construct, and Construct Page grant enforcement;
4. MFA and step-up flows;
5. cross-App session, grant-revocation, and membership-removal behavior;
6. webhook replay and outage behavior;
7. recovery and break-glass access;
8. rollback to the previous admin login path.

Disabling Payload's local strategy requires a separate approved production migration.