---
name: bijection-workos-authkit
description: "Evaluate and integrate the WorkOS AuthKit component with Bijection."
---

# 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.

## Integration workflow

1. Read the source README and package manifest at the recorded revision.
2. Confirm the required SDK, dependency availability, and runtime compatibility.
3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name.
4. Keep credentials in the project's existing secret store.
5. Follow the project's execution rules for verification and report what was actually checked.

## Original upstream skill

The following guidance describes @convex-dev/workos-authkit. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately.


> Agents: read this skill fully before writing code that uses WorkOS AuthKit. Follow the installation and configuration steps exactly.

# WorkOS AuthKit

## Instructions

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.

### Installation

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

Current npm version: `@convex-dev/workos-authkit@0.2.10`

## 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.

## When NOT to use

- When a simpler built-in solution exists for your specific use case
- If you are not using Convex as your backend
- When the functionality provided by WorkOS AuthKit is not needed

## Resources

- [npm package](https://www.npmjs.com/package/%40convex-dev%2Fworkos-authkit)
- [GitHub repository](https://github.com/get-convex/workos-authkit)
- [Live demo](https://github.com/get-convex/workos-authkit/tree/main/example)
- [Convex Components Directory](https://www.convex.dev/components/workos-authkit)
- [Convex documentation](https://docs.convex.dev)