Skip to main content

​
WorkOS AuthKit

OpenSync uses AuthKit React in the browser and validates WorkOS JWTs in Convex.

​
Configure your application

  1. Create a WorkOS application and enable your chosen sign-in providers.
  2. Register exact redirect URIs for each frontend:
  1. Add the corresponding origins to WorkOS’s allowed origins/CORS configuration. Origins omit /callback. A redirect URI alone does not configure CORS.
  2. Set homepage, login and sign-out URLs for your frontend. Keep staging and production application settings separate.
  3. Set WORKOS_CLIENT_ID and private WORKOS_API_KEY on the matching Convex deployment. Set VITE_WORKOS_CLIENT_ID to the same public client ID before building the frontend.
Locally, leaving VITE_REDIRECT_URI unset lets the app use the current origin. This supports either registered Vite port.

​
How the release authenticates

src/main.tsx mounts AuthKitProvider and ConvexProviderWithAuthKit. convex/auth.config.ts validates the WorkOS token issuer and signing keys. The app provisions its user record through its user function after sign-in; JWT configuration alone does not create a database user. The current integration uses AuthKit’s browser token storage. It does not require a server cookie password. Changing frontend hosting does not require rotating keys or changing the existing authentication issuer.

​
Owner access

The owner console checks verified identity claims on the server. Fork owners must replace the hosted email allowlist in convex/lib/adminPolicy.ts with their own identities. Configure the boolean email_verified claim in the WorkOS access token, then sign in again to obtain a fresh token. A database role or client-supplied email does not grant owner access.

​
Check the result

Sign in and reload /dashboard directly. Open Settings and return to the dashboard. For redirect errors, compare the exact callback with WorkOS. For CORS errors, compare the origin. For a rejected Convex token, confirm frontend and backend client IDs belong to the same environment. Do not paste callback authorization codes into configuration or issue reports.