Skip to main content

Automatic AuthKit Configuration

Convex can create AuthKit environments in a WorkOS account made on your behalf. By default WorkOS gives you only two environments, but giving each Convex dev deployment its own AuthKit environment is useful for isolating development user data and configuration changes between multiple developers or agents working in parallel.

The Convex CLI will configure AuthKit environments, regardless of whether Convex or you created them, if the WORKOS_CLIENT_ID and WORKOS_API_KEY environment variables are present in the build environment or the Convex deployment. While developing locally, Convex can write environment variables to .env.local to make setting up an AuthKit environment a breeze.

Getting Started​

Choose AuthKit as your authentication option in the create convex tool.

npm create convex@latest

These templates include a convex.json which cause an AuthKit environment for this deployment to be created and configured. With just npx convex dev you'll get a WorkOS environment all hooked up!

Going to production​

In the Convex dashboard settings for your production deployment, create an AuthKit environment in the WorkOS Authentication integration under settings, integrations. Copy these credentials to your hosting provider environment variables (in addition to other setup, like adding a production CONVEX_DEPLOY_KEY, setting the build command, and setting other framework-specific AuthKit environment variables).

Preview deployments​

In the Convex dashboard settings for any deployment in your project, create a new project-level AuthKit environment in the WorkOS Authentication integration under settings, integrations. Copy these credentials to your hosting provider environment variables (in addition to other setup, like adding a preview CONVEX_DEPLOY_KEY, setting the build command, and setting other framework-specific AuthKit environment variables).

How it works​

AuthKit provisioning and configuration is triggered by the presence of a convex.json file with an authKit section with a property corresponding to the type of code push: dev, preview, or prod.

If this section is present, an AuthKit environment may be provisioned (dev only), local environment variables set (dev only), and configured (all code push types).

Finding the AuthKit environment​

The CLI looks for WorkOS credentials WORKOS_CLIENT_ID and WORKOS_API_KEY in the following order:

  1. Environment variables in the build environment shell or .env.local file
  2. Convex deployment environment variables

In remote build environments (e.g. building a project in Vercel, Netlify, Cloudflare) if these two environment variables are not found, the build will fail.

During local dev, credentials are next fetched from the Convex Cloud API for a new or existing AuthKit environment. A link to this deployment in the WorkOS dashboard can be found in the Convex dashboard under the WorkOS integration.

Configuring the AuthKit environment​

Once credentials are found, the WORKOS_API_KEY is used to configure the environment based on the configure section of the relevant authKit object. This sets things like an environment's redirect URIs, allowed CORS origins.

Setting local environment variables​

For dev deployments only, environment variables are written to .env.local based on the localEnvVars section of the relevant authKit config.

Project-level vs deployment level AuthKit environments​

In hosting providers with remote build pipelines like Vercel, it's difficult to set environment variables like WORKOS_API_KEY at build time in a way that's available to server-side code like Next.js middleware. This makes it necessary set the WORKOS_* environment variables in advance for preview and production deployments built on these platforms.

After creating the WorkOS AuthKit environments for production and preview deployments in the dashboard, copy relevant environment variables like WORKOS_CLIENT_ID, WORKOS_API_KEY, WORKOS_REDIRECT_URI, and WORKOS_COOKIE_PASSWORD to the preview and production environment variables in your hosting provider.

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.

In the authKit section of convex.json, localEnvVars automate setting up dev environments by automatically setting the right environment variables in .env.local and automatically configuring the environment with a redirectUri`.

Environments for hosting providers in build environments like Vercel (production and preview deploys) can be configured at build time, but the environment variables for these build environments must be set manually in the build settings.

Here's a common setup for a project where production and preview deploys are deployed to from Vercel. Check your hosting provider's docs to substitute the right environment variables, and check the guide for using AuthKit with your framework of choice to customize this example.

convex.json
{
  "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}"]
      }
    }
  }
}

Additionally, for local dev in Next.js and TanStack Start, Convex automatically generates a WORKOS_COOKIE_PASSWORD if it's not already in .env.local.