# WorkOS AuthKit

WorkOS identity synchronization

- Package: @bijectionhq/workos-authkit
- Category: Authentication
- Status: Preview
- License: Apache-2.0
- Bijection source (repository access required): https://github.com/bijectionhq/workos-authkit/tree/c335349add05ce52547259d0c02fceb3c3d0b835
- Upstream: https://github.com/convex/workos-authkit/tree/0c318d8f22a41545cf72443030aff163644e5462
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/workos-authkit

## Get the source

Bijection repository access is required. Request access at https://bijection.com/contact.

```sh
git clone https://github.com/bijectionhq/workos-authkit.git
cd workos-authkit
git checkout c335349add05ce52547259d0c02fceb3c3d0b835
```

## Before using this component

Read the package README at the recorded revision for setup, dependencies, and API examples. Upstream documentation describes the original package and may differ from the Bijection adaptation. This is a source candidate for evaluation. Catalog inclusion does not establish npm availability or runtime qualification. Check compatibility with your SDK and deployment before adoption. External providers run their own compute.

## Upstream package documentation

Recorded 2026-10-23. This describes @convex-dev/workos-authkit; check the Bijection adaptation separately.

The WorkOS AuthKit component provides official integration between WorkOS AuthKit authentication and Convex databases. It automatically syncs user data from WorkOS to Convex via webhooks, handles WorkOS events like user creation and deletion with custom Convex functions, and supports WorkOS actions to control user registration and authentication flows. The component manages the complete lifecycle of auth data synchronization and event handling in a reliable, durable way.

### Use cases

- **Sync user profiles automatically** when you need WorkOS user data (email, firstName, lastName) to stay in sync with your Convex database without manual API calls
- **Handle user lifecycle events** to create related data like todo lists, user preferences, or team memberships when users are created, updated, or deleted in WorkOS
- **Control user registration flows** by implementing WorkOS actions that validate email domains, check invitation codes, or enforce custom business rules before allowing signup
- **Extend auth data with app-specific fields** by maintaining your own users table that references the synced WorkOS data and adds custom properties
- **Process additional WorkOS events** like session creation or team updates by configuring webhook handlers for any WorkOS event type

### How it works

The component installs as a standard Convex component using `app.use()` in your convex.config.ts file. You create an AuthKit client instance that connects to the component and register its HTTP routes to handle incoming webhooks from WorkOS.

Webhook events from WorkOS automatically trigger the component's internal functions to sync user data. You can extend this by defining event handlers using the `authKit.events()` method, which lets you respond to user.created, user.updated, user.deleted, and any additional WorkOS event types. Each handler receives a mutation context and typed event data.

For WorkOS actions, you use the `authKit.actions()` method to define handlers that can allow or deny authentication and registration attempts. The component provides response objects with `allow()` and `deny()` methods to control the outcome. All webhook signatures and action secrets are verified automatically using environment variables.

### Upstream README

This component is the official way to integrate WorkOS AuthKit authentication with your Convex project.

Features:

- Sync user data from WorkOS to your Convex database reliably and durably.
- Respond to events with Convex functions.
- Backfill existing WorkOS users when adding the component to an existing app.

See [example](./example) for a demo of how to incorporate this component into your application.

Open a [GitHub issue](https://github.com/get-convex/workos-authkit/issues) with
any feedback or bugs you find.

## Prerequisites

Follow the [Convex WorkOS AuthKit guide](https://docs.convex.dev/auth/authkit/)
to set up a working project with WorkOS AuthKit.

Then follow the steps below to set up user data syncing and event handling.

## Configure webhooks

User data syncing requires webhooks to be configured in your WorkOS project.

Select Webhooks from the left sidebar in your WorkOS project, and create a new
webhook with the following settings:

- **Endpoint URL**: `https://<your-convex-deployment>.convex.site/workos/webhook`
- **Events**: `user.created`, `user.updated`, `user.deleted`

![Webhook
configuration](https://raw.githubusercontent.com/get-convex/workos-authkit/refs/heads/main/assets/webhook-configuration.png)

Copy the webhook secret and add it to your environment variables as
`WORKOS_WEBHOOK_SECRET`.
![Webhook header](https://raw.githubusercontent.com/get-convex/workos-authkit/refs/heads/main/assets/webhook-header.png)

```sh
npx convex env set WORKOS_WEBHOOK_SECRET=<your-webhook-secret>
```

## Installation

First, add `@convex-dev/workos-authkit` to your Convex project:

```sh
npm install @convex-dev/workos-authkit
```

Then, install the component within your `convex/convex.config.ts` file:

```ts
// convex/convex.config.ts
import workOSAuthKit from "@convex-dev/workos-authkit/convex.config";
import { defineApp } from "convex/server";

const app = defineApp();
app.use(workOSAuthKit);
export default app;
```

Create a Convex AuthKit client within your `convex/` folder, and point it
to the installed component:

```ts
// convex/auth.ts
import { AuthKit } from "@convex-dev/workos-authkit";
import { components } from "./_generated/api";
import type { DataModel } from "./_generated/dataModel";

export const authKit = new AuthKit<DataModel>(components.workOSAuthKit);
```

Finally, register component webhook routes in `convex/http.ts`:

```ts
import { httpRouter } from "convex/server";
import { authKit } from "./auth";

const http = httpRouter();
authKit.registerRoutes(http);
export default http;
```

## Custom domain

If you've configured a [custom WorkOS authentication API domain](https://workos.com/docs/custom-domains/auth-api), pass it as `apiHostname` when constructing the AuthKit client. This routes the WorkOS SDK through your domain and updates the JWT issuer and JWKS URLs to match.

```ts
// convex/auth.ts
export const authKit = new AuthKit<DataModel>(components.workOSAuthKit, {
  apiHostname: "auth.example.com",
});
```

## Usage

User create/update/delete in WorkOS will be automatically synced by the
component.

Use the `getAuthUser` component method to get the current authenticated user
object:

```ts
export const getCurrentUser = query({
  args: {},
  handler: async (ctx, _args) => {
    const user = await authKit.getAuthUser(ctx);
    return user;
  },
});
```

## Events

The AuthKit component can be configured to handle events from WorkOS. This is
useful for running code when a user is created, updated, or deleted in WorkOS,
or in response to any other provided event.

By default the component will handle the following events:

- `user.created`
- `user.updated`
- `user.deleted`

```ts
// convex/auth.ts
import { AuthKit, type AuthFunctions } from "@convex-dev/workos-authkit";
import { components, internal } from "./_generated/api";
import type { DataModel } from "./_generated/dataModel";

// Get a typed object of internal Convex functions exported by this file
const authFunctions: AuthFunctions = internal.auth;

const authKit = new AuthKit<DataModel>(components.workOSAuthKit, {
  authFunctions,
});

// create `authKitEvent` as a named export
export const { authKitEvent } = authKit.events({
  "user.created": async (ctx, event) => {
    // ctx is a mutation context and event.data is typed
    await ctx.db.insert("todoLists", {
      name: `${event.data.firstName}'s Todo List`,
      userId: event.data.id,
    });
  },
});
```

### Additional event types

The component can handle any WorkOS event type. WorkOS docs provide a [complete
list of events](https://workos.com/docs/events). To handle an additional event
type, select it in your [webhook configuration](#configure-webhooks) and add a
handler for it.

```ts
// convex/auth.ts
import { AuthKit, type AuthFunctions } from "@convex-dev/workos-authkit";
import { components, internal } from "./_generated/api";
import type { DataModel } from "./_generated/dataModel";

const authFunctions: AuthFunctions = internal.auth;

const authKit = new AuthKit<DataModel>(components.workOSAuthKit, {
  authFunctions,
});

export const { authKitEvent } = authKit.events({
  "session.created": async (ctx, event) => {
    // do something with the session data
  },
  "session.revoked": async (ctx, event) => {
    // do something with the session data
  },
});
```

## User data

Most apps will need to control their user schema and be able to query directly
against a users table. The AuthKit component has it's own user table with user
data from WorkOS. You can think of this as auth metadata for your users, but
you'll likely want to extend this with additional data from your app.

A common pattern for this is to create your own users table with a reference to
the AuthKit user table, using the user events to do any necessary syncing.

```ts
// convex/auth.ts
import { AuthKit, type AuthFunctions } from "@convex-dev/workos-authkit";
import { components, internal } from "./_generated/api";
import type { DataModel } from "./_generated/dataModel";

const authFunctions: AuthFunctions = internal.auth;

const authKit = new AuthKit<DataModel>(components.workOSAuthKit, {
  authFunctions,
});

export const { authKitEvent } = authKit.events({
  "user.created": async (ctx, event) => {
    await ctx.db.insert("users", {
      authId: event.data.id,
      email: event.data.email,
      name: `${event.data.firstName} ${event.data.lastName}`,
    });
  },
  "user.updated": async (ctx, event) => {
    const user = await ctx.db
      .query("users")
      .withIndex("authId", (q) => q.eq("authId", event.data.id))
      .unique();
    if (!user) {
      console.warn(`User not found: ${event.data.id}`);
      return;
    }
    await ctx.db.patch(user._id, {
      email: event.data.email,
      name: `${event.data.firstName} ${event.data.lastName}`,
    });
  },
  "user.deleted": async (ctx, event) => {
    const user = await ctx.db
      .query("users")
      .withIndex("authId", (q) => q.eq("authId", event.data.id))
      .unique();
    if (!user) {
      console.warn(`User not found: ${event.data.id}`);
      return;
    }
    await ctx.db.delete(user._id);
  },

  // Handle any event type
  "session.created": async (ctx, event) => {
    console.log("onCreateSession", event);
  },
});
```

## Backfilling existing users

If you're adding this component to an app that already has users in WorkOS, you
can backfill them into the component's user table. The backfill also fires
`user.created` event handlers, so your app's own tables get populated too.

Export the backfill utility from your auth file:

```ts
// convex/auth.ts
export const { backfillUsers } = authKit.utils();
```

Then trigger it from the CLI or the Convex dashboard:

```sh
npx convex run auth:backfillUsers
```

The backfill processes users oldest-first. It's idempotent - if interrupted, just
run it again and it will skip users that are already synced.

## Actions

The AuthKit component can be configured to handle actions from WorkOS. Actions
allow you to block user registration or authentication based on your own logic.
Read more about actions in the [WorkOS
docs](https://workos.com/docs/authkit/actions).

## Configuration

1. Configure actions in your WorkOS dashboard.
2. Set the endpoint URL for your action(s) to
   `https://<your-convex-deployment>.convex.site/workos/action`
3. Copy the action signing secret from the dashboard and set it in your
   environment variables as `WORKOS_ACTION_SECRET`.

![Action
configuration](https://raw.githubusercontent.com/get-convex/workos-authkit/refs/heads/main/assets/action-configuration.png)

## Usage

Action handlers are defined using the `actions` method on the AuthKit component.
AuthKit actions must return a response payload that allows or denies the action,
so a response object is provided to the action handler with `allow` and `deny`
methods.

```ts
// convex/auth.ts
import { AuthKit, type AuthFunctions } from "@convex-dev/workos-authkit";
import { components, internal } from "./_generated/api";
import type { DataModel } from "./_generated/dataModel";

const authFunctions: AuthFunctions = internal.auth;

const authKit = new AuthKit<DataModel>(components.workOSAuthKit, {
  authFunctions,
});

export const { authKitAction } = authKit.actions({
  authentication: async (_ctx, _action, response) => {
    return response.allow();
  },
  userRegistration: async (_ctx, action, response) => {
    if (action.userData.email.endsWith("@gmail.com")) {
      return response.deny("Gmail accounts are not allowed");
    }
    return response.allow();
  },
});
```