ebon gulch
I would like you to help me figure out what is a good and safe workflow with Vercel, WorkOS and Convex using Previews.
Should each developer use their own "dev" deployment when working on a feature or should they connect to the generated "preview" deployment?
How to best manage users in each environment? WorkOS seems to have fixed environments so it doesn't seem possible to create users per preview deployment, all preview deployments will need to share the WorkOS preview environment.
worn pathBOT
Hi @ebon gulch. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:
Here’s what the docs and support threads support, and where they’re silent.
Per‑developer dev deployments are still the primary workflow.
npx convex dev. [Typical workflow]So for day‑to‑day feature work:
Preview deployments are for PR / branch review, not for local dev.
npx convex deploy in Vercel/Netlify, using a preview deploy key. [Preview deployments; Vercel previews]So the safe pattern is:
If you need a permanent shared environment (e.g. for beta testers):
So you might have:
The docs distinguish:
authKit.dev in convex.json, and write credentials into .env.local. [Automatic AuthKit; Project config]The docs explicitly say:
So for your question:
WorkOS seems to have fixed environments so it doesn't seem possible to create users per preview deployment, all preview deployments will need to share the WorkOS preview environment.
The docs confirm the recommended setup is:
They do not document a pattern where each preview deployment gets its own separate WorkOS environment, and they suggest that’s not the intended path.
Based on the docs:
npx convex dev → gets their own Convex dev deployment. [Typical workflow]authKit.dev in convex.json so Convex auto‑provisions/configures a WorkOS environment and writes WORKOS_* into .env.local. [Automatic AuthKit; Recommended config]Preview / PRs (Vercel)
CONVEX_DEPLOY_KEY for Vercel Preview env. [Vercel previews]WORKOS_* vars into Vercel Preview env. [Automatic AuthKit; Project vs deployment AuthKit]Staging (optional but often useful)
Production
WORKOS_* vars in Vercel Production env. [Config dev/prod instances; Recommended config]From the docs:
The docs do not describe a supported way to have per‑preview WorkOS environments automatically; they explicitly steer you toward shared project‑level environments for preview/prod. [Project vs deployment AuthKit]
ebon gulch
@worn path the linked documentation on how to get the auto-provisioning working is a bit sparce.
I have an existing WorkOS account. It is not clear to me how to proceed from there.
worn pathBOT
Let me check the knowledge base for you again. One moment! :books:
You’re right that it’s a bit split across pages. Here’s the flow that is documented for using an existing WorkOS account with Convex’s AuthKit integration.
From your existing WorkOS dashboard:
/callback route, e.g.<http://localhost:3000/callback> for local dev. [Convex & AuthKit]Then:
WORKOS_CLIENT_IDWORKOS_API_KEY [Convex & AuthKit]In your Convex project, create convex/auth.config.ts and wire it to your WorkOS Client ID.
The docs show this pattern (same for React and Next.js): [Client configuration; Next.js config]
// convex/auth.config.ts
const clientId = process.env.WORKOS_CLIENT_ID;
const authConfig = {
providers: [
{
type: "customJwt",
issuer: `<https://api.workos.com/`,>
algorithm: "RS256",
applicationID: clientId,
jwks: `<https://api.workos.com/sso/jwks/${clientId}`,>
},
{
type: "customJwt",
issuer: `<https://api.workos.com/user_management/${clientId}`,>
algorithm: "RS256",
jwks: `<https://api.workos.com/sso/jwks/${clientId}`,>
},
],
};
export default authConfig;
Then:
Add WORKOS_CLIENT_ID to your local .env (no NEXT_PUBLIC_): [Config dev/prod instances]
WORKOS_CLIENT_ID=client_01XXXXXXXXXXXXXXXXXXXXXXXX
In the Convex dashboard, set WORKOS_CLIENT_ID for your dev deployment to the same value. [Config dev/prod instances]
Run:
npx convex dev
This syncs auth.config.ts to the backend. If WORKOS_CLIENT_ID is missing, Convex will show an error with a link to set it in the dashboard. [Client configuration]
You now need the AuthKit SDK in your app and to point it at Convex.
For dev, the docs recommend: [Config dev/prod instances]
WORKOS_CLIENT_ID="client_01XXXXXXXXXXXXXXXXXXXXXXXX"
WORKOS_API_KEY="sk_test_..." # server-side only
WORKOS_COOKIE_PASSWORD="at_least_32_chars" # for Next.js AuthKit
NEXT_PUBLIC_WORKOS_REDIRECT_URI="<http://localhost:3000/callback">
(For React/Vite, use VITE_WORKOS_CLIENT_ID / VITE_WORKOS_REDIRECT_URI instead.) [Client configuration]
React:
npm install @workos-inc/authkit-react @convex-dev/workos
``` [[Client configuration](<https://docs.convex.dev/auth/authkit/#client-configuration>)]
Next.js:
npm install @workos-inc/authkit-nextjs @convex-dev/workos
``` [[Next.js config](<https://docs.convex.dev/auth/authkit/#nextjs>)]
Then follow the framework‑specific section:
AuthKitProvider and ConvexProviderWithAuthKit, passing WorkOS’s useAuth() hook. [Client configuration]middleware.ts using authkitMiddleware. [Next.js config]app/callback/route.ts with handleAuth()app/sign-in/route.ts using getSignInUrl()Auto‑provisioning is driven by convex.json and doesn’t require Convex to own your WorkOS account; it just needs WORKOS_CLIENT_ID and WORKOS_API_KEY to be present. [Automatic AuthKit]
A typical config: [Recommended configuration]
{
"authKit": {
"dev": {
"configure": {
"redirectUris": ["<http://localhost:3000/callback"],>
"appHomepageUrl": "<http://localhost:3000",>
"corsOrigins": ["<http://localhost:3000"]>
},
"localEnvVars": {
"WORKOS_CLIENT_ID": "${authEnv.WORKOS_CLIENT_ID}",
"WORKOS_API_KEY": "${authEnv.WORKOS_API_KEY}",
"NEXT_PUBLIC_WORKOS_REDIRECT_URI": "<http://localhost:3000/callback">
}
},
"preview": {
"configure": {
"redirectUris": ["<https://${buildEnv.VERCEL_BRANCH_URL}/callback"],>
"appHomepageUrl": "<https://${buildEnv.VERCEL_PROJECT_PRODUCTION_URL}",>
"corsOrigins": ["<https://${buildEnv.VERCEL_BRANCH_URL}"]>
}
},
"prod": {
"environmentType": "production",
"configure": {
"redirectUris": [
"<https://${buildEnv.VERCEL_PROJECT_PRODUCTION_URL}/callback">
],
"appHomepageUrl": "<https://${buildEnv.VERCEL_PROJECT_PRODUCTION_URL}",>
"corsOrigins": ["<https://${buildEnv.VERCEL_PROJECT_PRODUCTION_URL}"]>
}
}
}
}
What this does (per docs): [Automatic AuthKit]
npx convex dev / deploy:
WORKOS_CLIENT_ID / WORKOS_API_KEY (from your existing WorkOS account) in env or Convex dashboard.WORKOS_API_KEY to configure that WorkOS environment (redirect URIs, CORS, etc.).localEnvVars into .env.local.For preview/prod, the docs recommend using project‑level AuthKit environments and copying their credentials into your hosting provider’s env vars (e.g. Vercel). [Project vs deployment AuthKit]
If users can sign in via WorkOS but useConvexAuth() shows isAuthenticated: false, the docs list common causes: [Debugging authentication]
WORKOS_CLIENT_ID mismatch between Convex and WorkOS.aud claim in the WorkOS JWT (Convex requires aud to match your applicationID / client ID).
ebon gulch
@worn path how do I provision a WorkOS environment for each preview environment? How do I provision a WorkOS environment for each developer?
worn pathBOT
Let me check the knowledge base for you again. One moment! :books:
There isn’t a fully documented way to provision a separate WorkOS environment per Convex preview deployment or per developer. The docs describe what is supported and recommended, and it’s more limited than what you’re asking for.
Convex’s AuthKit integration can:
authKit.dev in convex.json. [Automatic AuthKit]WORKOS_CLIENT_ID and WORKOS_API_KEY are present. [Automatic AuthKit]The recommended pattern is:
authKit.dev. [Automatic AuthKit; Recommended config]The docs explicitly say:
Deployment-specific AuthKit environments can be created for any deployment are difficult set up automatically so shared project-level environments are generally a better fit. [Project vs deployment AuthKit]
So:
For dev, Convex can provision/configure AuthKit environments automatically when you have authKit.dev in convex.json. [Automatic AuthKit]
Example config: [Recommended config]
{
"authKit": {
"dev": {
"configure": {
"redirectUris": ["<http://localhost:3000/callback"],>
"appHomepageUrl": "<http://localhost:3000",>
"corsOrigins": ["<http://localhost:3000"]>
},
"localEnvVars": {
"WORKOS_CLIENT_ID": "${authEnv.WORKOS_CLIENT_ID}",
"WORKOS_API_KEY": "${authEnv.WORKOS_API_KEY}",
"NEXT_PUBLIC_WORKOS_REDIRECT_URI": "<http://localhost:3000/callback">
}
}
}
}
How this works, per docs: [Automatic AuthKit]
npx convex dev:
WORKOS_CLIENT_ID / WORKOS_API_KEY in the environment or in the Convex deployment.configure block.localEnvVars into .env.local for that developer.This is the documented mechanism for “per‑developer” WorkOS environments: each dev’s Convex dev deployment can have its own associated AuthKit environment, and Convex manages the wiring. [Automatic AuthKit]
For preview deployments (e.g. Vercel Preview):
authKit.preview in convex.json, but not provisioning a new WorkOS environment per preview deployment. [Automatic AuthKit; Project vs deployment AuthKit]The recommended setup is:
WORKOS_CLIENT_ID, WORKOS_API_KEY, etc. into your hosting provider’s Preview env vars (e.g. Vercel). [Automatic AuthKit; Project vs deployment AuthKit]Then use something like:
{
"authKit": {
"preview": {
"configure": {
"redirectUris": ["<https://${buildEnv.VERCEL_BRANCH_URL}/callback"],>
"appHomepageUrl": "<https://${buildEnv.VERCEL_PROJECT_PRODUCTION_URL}",>
"corsOrigins": ["<https://${buildEnv.VERCEL_BRANCH_URL}"]>
}
}
}
}
This means:
The docs explicitly note that deployment‑specific AuthKit environments are “difficult to set up automatically” and recommend shared project‑level environments instead; they do not document a supported way to auto‑provision a new WorkOS environment per preview deployment. [Project vs deployment AuthKit]
authKit.dev in convex.json. Convex can provision/configure a WorkOS AuthKit environment and write WORKOS_* into each dev’s .env.local. This is the documented way to get per‑developer environments. [Automatic AuthKit; Recommended config]authKit.preview and env vars in your hosting provider. [Project vs deployment AuthKit]
ebon gulch
@worn path okay so
npx convex dev convex can set up this environment if it manages WorkOSHow do I allow Convex to Manage WorkOS? Where are the settings for that?
worn pathBOT
Let me check the knowledge base for you again. One moment! :books:
You’ve summarized the model correctly, and your questions line up with how Convex’s AuthKit auto‑provisioning is intended to work.
The missing piece is: “letting Convex manage WorkOS” is done via the Convex dashboard integration + convex.json, not via a local config toggle.
Convex manages WorkOS AuthKit via:
authKit section in convex.json in your repo. [Automatic AuthKit; Project config]The docs describe it like this:
convex.json. [Automatic AuthKit]WORKOS_CLIENT_ID / WORKOS_API_KEY as AuthKit credentials for that project. Those are what ${authEnv.WORKOS_CLIENT_ID} / ${authEnv.WORKOS_API_KEY} refer to in convex.json. [Automatic AuthKit; Recommended configuration]Once that integration is set up, Convex has permission (via the stored WORKOS_API_KEY) to call the WorkOS API and configure environments.
Auto‑provisioning is triggered purely by convex.json + a code push (npx convex dev / npx convex deploy):
{
"authKit": {
"dev": {
"configure": {
"redirectUris": ["<http://localhost:3000/callback"],>
"appHomepageUrl": "<http://localhost:3000",>
"corsOrigins": ["<http://localhost:3000"]>
},
"localEnvVars": {
"WORKOS_CLIENT_ID": "${authEnv.WORKOS_CLIENT_ID}",
"WORKOS_API_KEY": "${authEnv.WORKOS_API_KEY}",
"NEXT_PUBLIC_WORKOS_REDIRECT_URI": "<http://localhost:3000/callback">
}
},
"preview": {
"configure": {
"redirectUris": ["<https://${buildEnv.VERCEL_BRANCH_URL}/callback"],>
"appHomepageUrl": "<https://${buildEnv.VERCEL_PROJECT_PRODUCTION_URL}",>
"corsOrigins": ["<https://${buildEnv.VERCEL_BRANCH_URL}"]>
}
},
"prod": {
"environmentType": "production",
"configure": {
"redirectUris": [
"<https://${buildEnv.VERCEL_PROJECT_PRODUCTION_URL}/callback">
],
"appHomepageUrl": "<https://${buildEnv.VERCEL_PROJECT_PRODUCTION_URL}",>
"corsOrigins": ["<https://${buildEnv.VERCEL_PROJECT_PRODUCTION_URL}"]>
}
}
}
}
Mechanics (from the docs): [Automatic AuthKit]
npx convex dev / deploy, the CLI:
WORKOS_CLIENT_ID / WORKOS_API_KEY:
.env.local.localEnvVars into .env.local for that developer.WORKOS_API_KEY to configure that WorkOS environment according to the configure block (redirect URIs, CORS, etc.).The “Convex manages WorkOS” part is exactly this: Convex holds the WorkOS API key (via the integration) and uses it automatically when it sees authKit in convex.json. [Automatic AuthKit]
For dev:
npx convex dev → Convex creates a dev deployment.authKit.dev present and the WorkOS integration configured, Convex:
WORKOS_CLIENT_ID / WORKOS_API_KEY / redirect URI into that dev’s .env.local according to localEnvVars. [Automatic AuthKit; Project vs deployment AuthKit]That’s how you get “Convex creates a dev environment for each developer” without any extra manual step beyond:
authKit.dev block in convex.json.The docs confirm your understanding:
authKit.prod and used by the production deployment. [Automatic AuthKit; Config dev/prod instances]authKit.preview.configure using buildEnv.VERCEL_BRANCH_URL, etc., so Vercel previews work with the shared secrets. [Recommended configuration]The docs explicitly say deployment‑specific AuthKit environments are “difficult to set up automatically” and recommend these shared project‑level environments for preview/prod. [Project vs deployment AuthKit]
So, concretely:
authEnv.WORKOS_CLIENT_ID / authEnv.WORKOS_API_KEY). [Automatic AuthKit]authKit section to convex.json (like the example above).npx convex dev:
WORKOS_* values into .env.local. [Automatic AuthKit]convex.json (with secrets redacted) and I can point out exactly what to add/change to align with this flow.
ebon gulch
@worn path I receive an error that "A WorkOS team already exists with <email>. Please select a different email address."
How can I connect the integration with an existing WorkOS project?
worn pathBOT
Let me check the knowledge base for you again. One moment! :books:
That specific error isn’t described in the docs, but there is a closely related limitation documented for the WorkOS integration: a single email address can only be associated with one WorkOS workspace. [Platform not authorized]
From the troubleshooting section:
You'll need to use a different email address to create your new WorkOS Workspace as an email address can only be associated with a single WorkOS workspace. [Platform not authorized]
So, based on what is documented:
They do document two supported paths when the integration is in a bad state:
Ask WorkOS to restore permissions if Convex was previously connected and then removed:
Disconnect and re‑provision the WorkOS integration from Convex’s side (this creates a new WorkOS workspace/team, not reuse an existing one):
npx convex integration workos disconnect-team
npx convex integration workos provision-team
However, the docs do not explain a flow like:
“I already have a WorkOS project X; please point this Convex project at that exact WorkOS project X instead of creating a new one.”
So I can’t give you a documented, step‑by‑step way to do that. The only clearly documented options are:
ebon gulch
Hi @worn path , I set things up and things are mostly working, but it seems to me that there is only one single preview environment? How can multiple people work in parallel in this setup? The convex.json does configure WorkOS on each preview deploy, but it does so with the latest preview deploy. Meaning if there are 2 people working in parallel, whoever pushed latest will overwrite the configurations of the preview environment.
worn pathBOT
Let me check the knowledge base for you again. One moment! :books:
You’ve understood the current behavior correctly, and the limitation you’re seeing is real given how AuthKit auto‑configuration works today.
For previews, Convex explicitly recommends project‑level (shared) AuthKit environments, not one per preview deployment:
Deployment-specific AuthKit environments can be created for any deployment are difficult set up automatically so shared project-level environments are generally a better fit. [Project vs deployment AuthKit]
And the recommended convex.json example shows a single authKit.preview block that uses Vercel build env vars to set redirect URIs / CORS for “preview” in general, not per‑deployment: [Recommended configuration]
"preview": {
"configure": {
"redirectUris": ["<https://${buildEnv.VERCEL_BRANCH_URL}/callback"],>
"appHomepageUrl": "<https://${buildEnv.VERCEL_PROJECT_PRODUCTION_URL}",>
"corsOrigins": ["<https://${buildEnv.VERCEL_BRANCH_URL}"]>
}
}
The auto‑provisioning flow is:
configure block. [Automatic AuthKit]So if two branches deploy in parallel, they are both configuring the same WorkOS preview environment; the last deploy “wins” in terms of redirect URIs / CORS.
The docs do not describe any mechanism to:
They explicitly say that deployment‑specific AuthKit environments are “difficult to set up automatically” and recommend shared project‑level ones instead. [Project vs deployment AuthKit]
Based on the docs, the intended parallel‑work story is:
The docs don’t offer a way around the “last deploy overwrites preview AuthKit config” issue; they just recommend this shared‑environment model for previews and per‑developer isolation at the dev‑deployment level.
So:
ebon gulch
@worn path "Their preview environments share one WorkOS preview environment whose redirect URIs / CORS are updated on each deploy."
In practice this means that only one preview branch can be active, so the entire team can only work on one feature at a time. Otherwise the Vercel preview deployments will be overwritten by eachother. If the CORS and callback URI settings don't work per Vercel preview deploy, then how can people share their work with QA for example?
<@&1228088700710293556> "Their preview environments share one WorkOS preview environment whose redirect URIs / CORS are updated on each deploy."
In practice this means that only one preview branch can be active, so the entire team can only work on one feature at a time. Otherwise the Vercel preview deployments will be overwritten by eachother. If the CORS and callback URI settings don't work per Vercel preview deploy, then how can people share their work with QA for example?
@worn path "Their preview environments share one WorkOS preview environment whose redirect URIs / CORS are updated on each deploy."
In practice this means that only one preview branch can be active, so the entire team can only work on one feature at a time. Otherwise the Vercel preview deployments will be overwritten by eachother. If the CORS and callback URI settings don't work per Vercel preview deploy, then how can people share their work with QA for example?
worn pathBOT
Let me check the knowledge base for you again. One moment! :books:
You’re right to call out this tension. The current docs describe the shared‑preview‑AuthKit model, but they don’t go on to explain “how to do QA on multiple branches at once” with it, and they don’t document a clean, fully isolated per‑preview‑branch AuthKit setup.
What is documented:
For preview deployments, Convex recommends project‑level (shared) AuthKit environments, not one per preview deployment:
Deployment-specific AuthKit environments can be created for any deployment are difficult set up automatically so shared project-level environments are generally a better fit. [Project vs deployment AuthKit]
The recommended authKit.preview config uses Vercel build env vars to set redirect URIs and CORS, but it still targets a single WorkOS preview environment: [Recommended configuration]
"preview": {
"configure": {
"redirectUris": ["<https://${buildEnv.VERCEL_BRANCH_URL}/callback"],>
"appHomepageUrl": "<https://${buildEnv.VERCEL_PROJECT_PRODUCTION_URL}",>
"corsOrigins": ["<https://${buildEnv.VERCEL_BRANCH_URL}"]>
}
}
On each preview deploy, the CLI:
WORKOS_CLIENT_ID / WORKOS_API_KEY.WORKOS_API_KEY to configure that environment according to the configure block. [Automatic AuthKit]There’s no mention of keeping multiple redirect/CORS configs in parallel for different preview URLs.
So, based on the docs alone:
They explicitly say that deployment‑specific AuthKit environments are “difficult to set up automatically” and recommend shared project‑level environments instead. [Project vs deployment AuthKit]
Because of that, the documentation does not give a clear, supported pattern that guarantees “any number of preview branches can all be QA’d simultaneously with independent AuthKit config.” It also doesn’t explicitly say “only one preview can be active,” but the behavior you’re describing (last deploy wins) is consistent with what’s written.
The only clearly documented ways to get isolation today are:
ebon gulch
Is it possible to point these developer environments in the preview build of vercel?
@worn path Is it possible to point these developer environments in the preview build of vercel?
So wh
worn pathBOT
Let me check the knowledge base for you again. One moment! :books:
I’m not seeing anything in the docs that describes a supported way to have a Vercel preview build automatically point at each developer’s personal dev deployment.
What is documented for Vercel previews is:
npx convex deploy with a preview deploy key. [Vercel previews]npx convex deploy will:
CONVEX_URL (or a similar env var) in the build environment so your frontend points at that preview deployment. [Vercel previews]npx convex env set --preview-name $VERCEL_GIT_COMMIT_REF ... in your build script. [Vercel URL env]The documented model is:
npx convex dev. [Understanding dev deployments]There’s no mention of wiring Vercel previews to personal dev deployments, and the CLI options around previews (--preview-create, --preview-run, --preview-name for env set) all operate on preview deployments, not dev ones. [CLI deploy; Vercel URL env]
So, based on the docs:
ebon gulch
@worn path maybe I am misunderstanding, is it possible that in the shared preview WorkOS environment the integration sets multiple redirect URL-s up, and thus each active Vercel preview deployment can work with the shared data?
worn pathBOT
Let me check the knowledge base for you again. One moment! :books:
The knowledge sources don’t say this explicitly, but they strongly suggest the opposite: the current Convex+AuthKit integration assumes one WorkOS preview environment whose redirect/CORS config is overwritten on each preview deploy, not accumulated.
What we do know from the docs:
For previews, Convex recommends a shared, project‑level AuthKit environment, not one per preview deployment. [Project vs deployment AuthKit]
On each code push, the CLI:
uses
WORKOS_API_KEYto configure the environment based on theconfiguresection of the relevantauthKitobject. [Automatic AuthKit]
The recommended authKit.preview config is:
"preview": {
"configure": {
"redirectUris": ["<https://${buildEnv.VERCEL_BRANCH_URL}/callback"],>
"appHomepageUrl": "<https://${buildEnv.VERCEL_PROJECT_PRODUCTION_URL}",>
"corsOrigins": ["<https://${buildEnv.VERCEL_BRANCH_URL}"]>
}
}
There is no mention of Convex appending to an existing list of redirect URIs / CORS origins in WorkOS, or of keeping multiple preview URLs active at once. The wording “configure the environment based on the configure section” reads as “set it to this,” not “merge with what’s already there,” and nothing in the docs describes multi‑preview coexistence.
So:
convex.json for this deploy,” and