Authentication Flow & Clerk Integration
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Barekey platform utilizes Clerk as its primary provider for authentication and organization management. This integration ensures a secure, scalable, and developer-friendly experience for managing secrets. Clerk handles user identities, session persistence, and multi-tenant organization structures, while the backend, powered by Convex, validates these identities to authorize database operations.
The authentication flow is integrated into the React SPA using the @clerk/react-router SDK and synchronized with Convex through a dedicated provider. This setup allows the application to enforce access controls based on both individual user identity and active organization membership.
Sources: AGENTS.md:27-28, AGENTS.md:43-50
Single Sign-On (SSO) and Login Methods
Barekey supports multiple authentication strategies via Clerk, including OAuth providers (Google and GitHub), Passkeys, and a specialized "Dev" login for local development environments.
Supported Strategies
- OAuth (Google/GitHub): Uses standard redirect flows to authenticate users through third-party providers.
- Passkeys: Utilizes the WebAuthn API for passwordless, biometric-secured authentication.
- Dev Login: A development-only feature that creates a sign-in token via a Convex action (
api.dev_auth.createSignInTokenForDevUser) to bypass external providers during local testing.
Sources: pkg/ui/src/pages/auth/sso/page.tsx:49-115, AGENTS.md:28
Authentication UI Flow
The SSO page manages the initiation of these authentication sessions and handles potential errors during the handshake.
Diagram showing the various entry points for user authentication and the path to session completion.
Sources: pkg/ui/src/pages/auth/sso/page.tsx:50-120
Convex Backend Validation
When the frontend communicates with Convex, the backend must verify the user's identity. Convex uses the ctx.auth.getUserIdentity() method to retrieve the Clerk JWT payload.
Authorization Helpers
A set of utility functions in pkg/convex/lib/auth.ts is used to enforce security boundaries within Convex functions:
| Function | Purpose |
|---|---|
requireIdentity | Throws an error if the user is not authenticated. |
requireActiveOrgIdClaims | Extracts and validates the active organization ID from the JWT. |
assertExpectedOrgSlug | Verifies that the organization slug in the request matches the slug in the user's claims. |
getActiveOrgIdClaimsOrNull | Returns claims if available, otherwise null (used for non-blocking queries). |
Sources: pkg/convex/lib/auth.ts:18-70, AGENTS.md:46
Data Access Flow
Sequence diagram illustrating how Convex validates the Clerk-provided identity before processing backend requests.
Sources: pkg/convex/lib/auth.ts:18-35, AGENTS.md:46-47
Organization & Workspace Integration
Clerk's organization management is deeply integrated into the Barekey routing and data model. Every project in Barekey must be owned by an organization, never an individual user.
Organization Bootstrapping
Upon first login, the system attempts to resolve the user's active organization. If no organizations exist, the select page provides an automated bootstrapping process:
- Auto-creation: Generates an organization named "'s Organization".
- Slug Generation: Creates a unique slug based on the user's name or email (e.g.,
johndoeorg5831). - Activation: Uses Clerk's
setActivemethod to set the newly created organization as the active context.
Sources: pkg/ui/src/pages/o/select/page.tsx:35-80, AGENTS.md:49-50
Workspace Verification
The Page component in pkg/ui/src/pages/home/page.tsx acts as a guard. It ensures that:
- The user is signed in.
- The Convex authentication state is synchronized (
isAuthenticated). - The user is redirected to a specific organization overview if an
orgSlugis present, or the organization selection page otherwise.
Sources: pkg/ui/src/pages/home/page.tsx:16-35
Advanced Diagnostics & Troubleshooting
To handle potential drift between Clerk's active session and the frontend routes, the application includes a diagnostics panel.
| Diagnostic Field | Source | Description |
|---|---|---|
| Workspace ID | orgClaims.orgId | The unique internal identifier for the organization. |
| Workspace Role | orgClaims.orgRole | The user's role (e.g., org:admin, org:member). |
| Route Aligned | orgClaims.routeMatchesActiveOrg | Boolean indicating if the URL slug matches the session organization. |
| Signed In | orgClaims.isSignedIn | Confirmation of the current authentication state. |
Sources: pkg/ui/src/pages/o/[org]/settings/page.tsx:230-265
Conclusion
The authentication system effectively leverages Clerk for identity and organization logistics while utilizing Convex for secure, role-based backend authorization. By enforcing organization ownership for all projects and providing robust bootstrapping for new users, Barekey maintains a strict multi-tenant architecture with high developer convenience.