> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bijection.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Bijection & WorkOS AuthKit

> Integrate WorkOS AuthKit authentication with Bijection

export const provider_0 = "AuthKit"

export const configProp_0 = 
<>
  the{" "}
  <a
    href="https://workos.com/docs/user-management/vanilla/nodejs/1-configure-your-project/configure-a-redirect-uri"
    target="_blank"
  >
    <code>redirectUri</code>
  </a>{" "}
  prop
</>

export const providerProvider_0 = <code>AuthKitProvider</code>

export const integrationProvider_0 = <code>BijectionProviderWithAuthKit</code>

[WorkOS AuthKit](https://authkit.com) is an authentication solution that enables
sign-in using passwords, social login providers, email one-time codes,
two-factor authentication, and user management capabilities.

You can use your own WorkOS account with AuthKit or let Bijection create a managed
WorkOS team which enables provisioning and configuration of AuthKit environments
automatically.

The docs below are targeted at starting a new project with WorkOS AuthKit and
Bijection. If you have an existing app that you'd like to migrate, see the
[Add to Existing App](/auth/authkit/add-to-app) instructions instead.

## Get started

[Install the Bijection CLI](/get-started/install) and create a new app with
`bijection init`, choosing the `react-vite` or `nextjs` template:

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection init my-app --template react-vite
cd my-app
```

Add AuthKit to it with the [Add to Existing App](/auth/authkit/add-to-app)
instructions, then start the backend in dev mode:

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection dev
```

To connect WorkOS, follow the instructions in one of the sections below.

## Option 1: use a Bijection-managed WorkOS team&#x20;

<Tip>
  Choose this option if you're new to WorkOS or if you want the convenience of
  the auto-provisioning and auto-configuration that the full integration offers.
</Tip>

<Info>
  Permissions: provisioning the Bijection-managed WorkOS team, disconnecting it,
  inviting WorkOS team members, and creating/deleting shared project-level
  WorkOS environments all require **team admin** (or project admin, for the
  project-level operations). Provisioning a WorkOS environment for an individual
  deployment uses the same permission as managing that deployment, so any team
  member can self-serve a WorkOS env for their dev/preview deployment but only
  admins can do so for production.
</Info>

Follow the prompts to create a WorkOS team that will be associated with your
Bijection team. After this, team members of this Bijection team can self-serve WorkOS
environments for their dev/preview deployments, and team admins can provision
shared project-level environments and production envs.

See what additional functionality is available in [Next steps](#next-steps) and
see [AuthKit configuration in bijection.json](/auth/authkit/auto-provision) to
modify the bijection.json file in this template for your needs.

<Accordion title="What if I already have a WorkOS team but want to use the Bijection-managed features?">
  If you you are an existing WorkOS user but want the Bijection auto-configuration
  and auto-provisioning support, you'll need to **start with a new WorkOS team**
  that is managed by Bijection. To do that, make sure you select an email address
  that isn't already associated with a WorkOS team when prompted. The email
  address will need to be linked with your Bijection account. You can
  [link additional email addresses](https://console.bijection.com) to your
  Bijection account in the console. Depending on your email provider, you might be
  able to use a `+` address for this step (e.g. `your.name+workos@example.com`) to
  avoid having to create an entirely new email account.

  If using **an existing WorkOS team** is more important than the
  auto-provisioning and auto-configuration support, you should exit out of the
  prompt flow triggered by `npm run dev` and follow along with
  [the section below](#option-2-use-an-existing-workos-team) instead. Just note that using an existing
  team means that *Bijection won't be able to auto-configure new applications or
  auto-provision WorkOS environments for each of your deployments.*
</Accordion>

## Option 2: use an existing WorkOS team&#x20;

<Tip>
  Choose this option if you're an established WorkOS AuthKit user and using your
  existing WorkOS team is more important than the auto-provisioning and
  auto-configuration that the full integration offers.
</Tip>

When you are prompted to create a new WorkOS team, choose No.

You'll then need to manually configure your Bijection deployment and client
framework.

<Steps>
  <Step title="Find your WorkOS Client ID and API Key">
    From the WorkOS dashboard [get started](https://dashboard.workos.com/get-started) page under **Quick start**, find your
    `WORKOS_CLIENT_ID` and `WORKOS_API_KEY`.

    <p style={{textAlign: 'center'}} />
  </Step>

  <Step title="Set the values in your deployment">
    Use the `bijection` CLI to set environment variables for `WORKOS_CLIENT_ID`
    and `WORKOS_API_KEY` with values from the WorkOS dashboard in the previous step.

    ```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
    bijection env set WORKOS_CLIENT_ID $YOUR_CLIENT_ID_HERE
    bijection env set WORKOS_API_KEY $YOUR_API_KEY_HERE
    ```
  </Step>

  <Step title="Deploy your application">
    Run `bijection dev` to automatically sync your configuration to your backend.

    ```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
    bijection dev
    ```
  </Step>
</Steps>

<Info>
  For multiple Bijection applications integrated with an existing WorkOS team
  you'll need to decide if the [single-tenant or multi-tenant
  model](https://workos.com/docs/authkit/modeling-your-app/single-tenant-and-multi-tenant-models)
  is right for your situation. That may include manually provisioning additional
  WorkOS environments.
</Info>

## Next steps

### Syncing data and handling events using the WorkOS Component

You can integrate the
WorkOS Component into your
application to sync user data into your application and handle other events
(like account lifecycle) from WorkOS.

### Accessing user information in functions

See [Auth in Functions](/auth/functions-auth) to learn about how to access
information about the authenticated user in your queries, mutations and actions.

See [Storing Users in the Bijection Database](/auth/database-auth) to learn
about how to store user information in the Bijection database.

### Accessing user information client-side

To access the authenticated user's information, use AuthKit's `User` object,
which can be accessed using AuthKit's
[`useAuth()`](https://github.com/workos/authkit-react?tab=readme-ov-file#useauth)
hook. For more information on the `User` object, see the
[WorkOS docs](https://workos.com/docs/reference/user-management/user).

```tsx components/Badge.tsx theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
export default function Badge() {
  const { user } = useAuth();

  return <span>Logged in as {user.firstName}</span>;
}
```

## Configuring dev and prod instances

To configure a different AuthKit instance between your Bijection development and
production deployments, you can use environment variables configured on the
Bijection console and referenced in `bijection/auth.config.ts`.

As long as you followed the instructions for
[adding AuthKit to an existing Bijection app](/auth/authkit/add-to-app), your
`bijection/auth.config.ts` file will make use of the `WORKOS_CLIENT_ID` value
referenced below.

<Accordion title="Sample auth.config.ts">
  ```ts bijection/auth.config.ts theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  const clientId = process.env.WORKOS_CLIENT_ID;

  const authConfig = {
    providers: [
      {
        type: "customJwt",
        issuer: `https://api.workos.com/`,
        algorithm: "RS256",
        jwks: `https://api.workos.com/sso/jwks/${clientId}`,
        applicationID: clientId,
      },
      {
        type: "customJwt",
        issuer: `https://api.workos.com/user_management/${clientId}`,
        algorithm: "RS256",
        jwks: `https://api.workos.com/sso/jwks/${clientId}`,
      },
    ],
  };

  export default authConfig;
  ```
</Accordion>

**Development configuration**

In the left sidenav of the Bijection [console](https://console.bijection.com),
switch to your development deployment and set the `WORKOS_CLIENT_ID` environment
variable to your development WorkOS Client ID.

Then, to switch your deployment to the new configuration, run `bijection dev`.

**Production configuration**

In the left sidenav of the Bijection [console](https://console.bijection.com),
switch to your production deployment and set the `WORKOS_CLIENT_ID` environment
variable to your production WorkOS Client ID.

Then, to switch your deployment to the new configuration, run
`bijection deploy`.

### Configuring WorkOS AuthKit's API keys

WorkOS AuthKit's API keys differ depending on whether they are for development
or production. Don't forget to update the environment variables in your `.env`
file as well as your hosting platform, such as Vercel or Netlify.

**Development configuration**

WorkOS API Key for development follows the format `sk_test_...`. WorkOS Client
ID for development follows the format `client_01...`.

```env .env.local theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
WORKOS_CLIENT_ID="client_01XXXXXXXXXXXXXXXXXXXXXXXX"
WORKOS_API_KEY="sk_test_..."
WORKOS_COOKIE_PASSWORD="your_secure_password_here_must_be_at_least_32_characters_long"
NEXT_PUBLIC_WORKOS_REDIRECT_URI="http://localhost:3000/callback"
```

**Production configuration**

WorkOS API Key for production follows the format `sk_live_...`. WorkOS Client ID
for production follows the format `client_01...`.

```env .env theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
WORKOS_CLIENT_ID="client_01XXXXXXXXXXXXXXXXXXXXXXXX"
WORKOS_API_KEY="sk_live_..."
WORKOS_COOKIE_PASSWORD="your_secure_password_here_must_be_at_least_32_characters_long"
NEXT_PUBLIC_WORKOS_REDIRECT_URI="https://your-domain.com/callback"
```

## Under the hood

The authentication flow looks like this under the hood:

1. The user clicks a login button
2. The user is redirected to a page where they log in via whatever method you
   configure in {provider_0}
3. After a successful login {provider_0} redirects back to your page, or a
   different page which you configure via {configProp_0}.
4. The {providerProvider_0} now knows that the user is authenticated.
5. The {integrationProvider_0} fetches an auth token from {provider_0}.
6. The `BijectionReactClient` passes this token down to your Bijection backend to
   validate
7. Your Bijection backend retrieves the public key from {provider_0} to check
   that the token's signature is valid.
8. The `BijectionReactClient` is notified of successful authentication, and
   {integrationProvider_0} now knows that the user is authenticated with
   Bijection. `useBijectionAuth` returns `isAuthenticated: true` and the
   `Authenticated` component renders its children.

{integrationProvider_0} takes care of refetching the token when needed to
make sure the user stays authenticated with your backend.