# WorkOS Documentation

> WorkOS provides developer-friendly APIs for enterprise features like Single Sign-On, Directory Sync, User Management, Admin Portal, Audit Logs, and more. This documentation site helps developers implement these features.

This documentation site provides guides, references, and examples for implementing WorkOS features in your applications.

- [Postman](#postman)
- [On prem deployment](#on-prem-deployment)
- [Glossary](#glossary)
- [Email](#email)
- [Widgets](#widgets)
- [Vault](#vault)
- [Single Sign-On](#sso)
- [Sdks](#sdks)
- [API Reference](#reference)
- [RBAC](#rbac)
- [Pipes](#pipes)
- [Migrations](#migrate)
- [Multi-Factor Auth](#mfa)
- [Magic Link](#magic-link)
- [Integrations](#integrations)
- [FGA](#fga)
- [Feature Flags](#feature-flags)
- [Events](#events)
- [Domain Verification](#domain-verification)
- [Directory Sync](#directory-sync)
- [Docs](#demo)
- [Custom Domains](#custom-domains)
- [AuthKit](#authkit)
- [Audit Logs](#audit-logs)
- [Admin Portal](#admin-portal)

## Postman {#postman}

### WorkOS Postman collection

Test the WorkOS API with Postman.

## Introduction

Postman is a popular API development tool that allows users to easily test API endpoints. The [WorkOS API collection](https://www.postman.com/workos/workspace/workos-public/collection/25188762-79ce1172-4741-4f1d-a486-64380f9a599f?ctx=documentation) is a set of pre-configured requests specific to the WorkOS API, meant to help developers to quickly get started testing the WorkOS API endpoints.

The [environment template](https://www.postman.com/workos/workspace/workos-public/environment/25188762-b99e7518-d907-4aa0-82d2-a199157a53c7) supports this collection, and allows variables to be abstracted away from the individual requests. The environment template makes it easier to manage and re-use common variables across the collection’s requests.

## Configuring Postman

There are several ways to use this collection. You can create a fork, or you can export/import the collection and environment.

### Creating a fork

The preferred and simplest way to get started using the WorkOS API collection is to create a fork of the collection and environment.

To create a fork of the collection, first sign in to your Postman account. Then navigate to the WorkOS API collection. Hover over the name of the collection and click the three dots, then click "Create a fork".

![A screenshot showing how to fork a collection in Postman](https://images.workoscdn.com/images/a3d67b02-a824-4f27-b055-c06eaf5a7e94.png?auto=format&fit=clip&q=50)

Select your fork label and workspace, then click the "Fork collection" button.

![A screenshot showing the fork collection details page in Postman.](https://images.workoscdn.com/images/c9074bd3-8ab8-4864-9b68-56c6a858a17e.png?auto=format&fit=clip&q=50)

You will now see the WorkOS API collection appear in your workspace’s collection tab.

To fork the WorkOS environment template, the same process is used. Navigate to the environments tab of the WorkOS Public workspace. Hover over the WorkOS environment template, click the three dots, and then click "Create a fork". Select your fork label and workspace, then click the "Fork environment" button.

### Exporting the collection and environment

Another way to use the WorkOS API collection is to import the collection and environment into your workspace. Using this approach allows you to share the collection as a JSON file to easily share it with others.

To export the collection, navigate to the collection tab in the WorkOS workspace, then hover over the WorkOS API collection name and click on the three dots. Click export to download the collection as a JSON file.

![A screenshot showing the export option in Postman.](https://images.workoscdn.com/images/54aed639-6c8f-467e-baa6-53099c36fe35.png?auto=format&fit=clip&q=50)

Navigate to your workspace’s collections tab and click on the import button.

![A screenshot showing where to find the import button in Postman.](https://images.workoscdn.com/images/802d9d45-c258-4548-9f88-7d04f2d260c2.png?auto=format&fit=clip&q=50)

Select the JSON file that was downloaded in the previous step and then click import. You will now see the collection available to use and edit in the collection tab.

The environment can be exported from the WorkOS workspace and imported to your personal workspace using these same steps.

Navigate to the collection tab in your workspace and select the environment. This allows the collection to reference the environment variables.

## Environment variables

The WorkOS API collection makes use of environment variables. All environment variables that are used in the WorkOS API collection are defined in the environment tab in Postman.

![A screenshot showing the environments tab in Postman.](https://images.workoscdn.com/images/bd26c85b-8d66-478c-909b-f5ee01ffaffd.png?auto=format&fit=clip&q=50)

To get started, you will need to obtain the `api_key` and `client_id` values from your WorkOS dashboard and enter them in the environment template.

You can find your API key and the client ID on the [API Keys](https://dashboard.workos.com/api-keys) page in the WorkOS dashboard.

There are also several other environment variables in the template which will need to be replaced with various IDs and values in the course of making API calls. These values are defined in the variable descriptions.

## Sending requests to the WorkOS API

The WorkOS collection sends data in several ways. Some requests use values directly in the URL, some requests use query parameters, and some requests send data in the body of the request. Each call will indicate where there are values present with a green dot.

The "Get A Directory User" request for instance uses the `api_key` environment variable in the authorization tab of the request, and the `base_url` and `directory_user_id` values in the URL of the request.

![A screenshot showing the Get a Directory User request in Postman.](https://images.workoscdn.com/images/76d3df52-cf4e-467a-a898-df62a920a800.png?auto=format&fit=clip&q=50)

The "Generate a Portal Link" request uses the `base_url` and `api_key` variables in the same way that the Get A Directory User call does, but also sends the name of the Organization and intent in the body of the request as x-www-form-urlencoded data.

![A screenshot showing the Generate a Portal Link request in Postman.](https://images.workoscdn.com/images/c2ae7131-dc79-49ee-aac1-724d3de42c48.png?auto=format&fit=clip&q=50)

To send a request, first select the WorkOS environment template so the collection has access to its variables.

![A screenshot showing where to select the Environment in Postman.](https://images.workoscdn.com/images/fea5d174-0fea-400b-b498-3753c85c5eeb.png?auto=format&fit=clip&q=50)

Finally, ensure all the values are defined where they are needed for the particular request and then click send.

## Debugging requests

Postman provides a developer console if you need to debug any requests. Navigate to a request and click on the console button to view the details of the requests you send.

![A screenshot showing the developer console in Postman.](https://images.workoscdn.com/images/9dafe4a0-5a9a-46d3-bee9-ba01d5b25724.png?auto=format&fit=clip&q=50)

If you have any questions while using the WorkOS API collection, please reach out to our team at [support@workos.com](mailto:support@workos.com).


## On prem deployment {#on-prem-deployment}

### Using WorkOS with On-prem Customers

Best practices for using WorkOS with on-prem customers.

## Introduction

WorkOS can be used with both cloud and on-prem deployments. This guide explains the considerations needed to use WorkOS features with on-prem deployment strategies. For example, many SaaS companies offer enterprise solutions where their infrastructure can be deployed to a customer's cloud or data center.

When using an on-prem deployment strategy, two key considerations are:

- Deploying a static API key to each customer's installation to isolate access to their team only
- Ensuring your customer's network can send and receive requests from the WorkOS API

Outside of these considerations, WorkOS integration for on-prem customers functions in the same way as in cloud deployments.

![diagram showing on-prem configuration using WorkOS](https://images.workoscdn.com/images/17460e43-790f-4791-93ee-f0b001ef5eae.png?auto=format&fit=clip&q=50)

## Using a static API key for each customer's deployment

Since a full deployment of your software is being deployed to your customer's environment, each deployment requires its own unique WorkOS API key. This can be accomplished by creating a separate environment in your WorkOS dashboard for each on-prem customer.

Each WorkOS workspace comes with Staging and Production environments by default. To create a new environment for an on-prem customer:

- Reach out to the WorkOS support team at [support@workos.com](mailto:support@workos.com)
- Provide the name you'd like to use for the new environment and specify that it should be a production environment

![diagram showing different environments in the WorkOS dashboard](https://images.workoscdn.com/images/2e280efe-011f-4583-9c67-1fedd60f0071.png?auto=format&fit=clip&q=50)

The support team will create the environment, which will then be available in the environments dropdown menu in your WorkOS workspace.

To retrieve the client ID and API key for this environment, navigate to the [API Keys section](https://dashboard.workos.com/api-keys) of the WorkOS dashboard where the values are available to download.

## Allowing WorkOS Traffic Through Firewalls

A common challenge with on-premise deployments is coordinating which traffic will be allowed by the firewall. Several strategies exist for allowing traffic to and from WorkOS to communicate with an on-prem deployment.

### Strategy 1: Configure Firewall Rules or ACLs

The most common approach is to deploy your application with the WorkOS integration to your customer's on-prem environment configured the same as you would for cloud application users, then have the firewall rules or access control lists (ACLs) set to allow WorkOS API traffic.

WorkOS uses Cloudflare to ensure security and reliability. If you need to allowlist IP addresses for redirect requests, you can use the IP ranges listed in the [Cloudflare documentation](https://www.cloudflare.com/ips/).

![diagram showing different environments in the WorkOS dashboard](https://images.workoscdn.com/images/23e605b6-2b82-41be-a93b-664d07b07d0a.png?auto=format&fit=clip&q=50)

#### Firewall Ingress Rules (Incoming Traffic)

Ingress rules control external traffic entering your network. Some features of WorkOS require requests originating from our APIs directly to the on-prem installation, such as authentication callbacks, action callbacks, and webhooks.

Events can also be ingested with the Events API, which is the preferred method for event delivery in an on-prem deployment scenario since those requests will originate from your on-prem application infrastructure.

- All requests use HTTPS on port 443
- All authentication requests originate from [Cloudflare's published IP ranges](https://www.cloudflare.com/ips/)
- All outbound requests for [Actions Webhooks](/authkit/actions) and [event and log streaming](/events/observability/datadog) will originate from the following IP ranges:

  - 3.217.146.166
  - 23.21.184.92
  - 34.204.154.149
  - 44.213.245.178
  - 44.215.236.82
  - 50.16.203.9
  - 52.1.251.34
  - 52.21.49.187
  - 174.129.36.47

- Requests will require an external domain name that resolves to the installation's host

#### Firewall Egress Rules (Outgoing Traffic)

Egress rules manage traffic leaving your network to external services.

Key aspects include:

- All requests leave the on-prem network over HTTPS on port 443
- All traffic is handled on Cloudflare's published IP ranges

##### Best Practices

- Apply the principle of least privilege
- Log and monitor cross-boundary traffic
- Regularly audit firewall rules

Implement a workflow of starting with restrictive default deny rules, then carefully opening only necessary ports and protocols to ensure that your integration with WorkOS is secure.

### Strategy 2: Use ngrok for Network Traffic Management

Another approach is to use a service like [ngrok](https://ngrok.com/) to manage traffic to and from the WorkOS API instead of modifying firewall rules. This approach allows you to implement WorkOS authentication without adjusting firewall configurations.

With ngrok, you can:

- Create secure tunnels from the public internet to your on-premise deployment
- Receive webhook events from WorkOS directly to your local development environment
- Implement WorkOS AuthKit, SSO and Directory Sync features in environments with restrictive network policies

Implementation involves installing the ngrok client on your application server, establishing a tunnel to your application's local port, and configuring your WorkOS integration to use the ngrok-provided public URL.

![diagram showing a WorkOS on-prem configuration using ngrok ](https://images.workoscdn.com/images/42766c0c-741c-460f-818f-6bb4875634ca.png?auto=format&fit=clip&q=50)

This approach requires configuration of third-party software and additional cost. ngrok offers different pricing tiers based on your needs, with paid plans providing features like persistent URLs, IP restrictions, and additional security controls essential for production environments.

## Air-Gapped Environments

For customers operating in air-gapped environments with no external network connectivity, cloud-based authentication services like WorkOS cannot be utilized as they require API connectivity.

However, many organizations with air-gapped environments have established security protocols that permit the deployment of approved third-party software within their isolated networks, as their security architecture already provides robust authentication mechanisms internally.

In these scenarios, we recommend a dual-implementation approach:

- Continue leveraging WorkOS for authentication in cloud-based and network-connected on-premises deployments
- Develop a specialized deployment package for air-gapped environments that:
  - Integrates with the customer's existing internal authentication infrastructure
  - Maintains feature parity while operating independently of external services
  - Adheres to the security policies specific to air-gapped environments

This approach allows you to maintain a consistent product experience across different deployment scenarios while accommodating the strict security requirements of air-gapped customers.


## Glossary {#glossary}

### Glossary

Terminology and concepts used in the WorkOS documentation.

## Access Token

An access token represents the successful authorization of your application to access a user’s profile. During the Single Sign-On authorization flow, you’ll receive an access token and profile in exchange for your authorization code.

## ACS URL

An Assertion Consumer Service URL (ACS URL) is an endpoint where an identity provider posts SAML responses.

## API Key

A unique identifier used to authenticate your API requests.

## Attribute Mapping

Attribute mapping allows IT administrators to customize the user claims that are sent to your application. WorkOS normalizes these claims, so you can depend on a reliable, expected set of user profile information.

## Authorization Code

An authorization code is a temporary code that you will exchange for an access token. During the Single Sign-On authorization flow, you’ll exchange your authorization Code for an access token and profile.

## Authentication Challenge

An authentication challenge, also known as challenge-response authentication, is a set of protocols that helps validate actions and protect resources from unauthorized access.

## Authentication Factor

An authentication factor is a category of credential that is intended to verify, sometimes in combination with other factors, that an entity requesting access to some system is who, or what, they are declared to be.

## Authorization URL

An authorization URL is the location your user will be directed to for authentication.



## Bearer Token

A Bearer Token is an HTTP authentication scheme that uses a single security token to act as the authentication of an API request. The client must send this token in the Authorization header when making requests to protected resources.

In the context of a Directory Sync integration, a Bearer Token is generated by WorkOS for SCIM providers such as Okta to authenticate endpoint requests.



## CIMD

Client ID Metadata Document (CIMD) is the mechanism through which an MCP client identifies itself to an authorization server. You can use WorkOS and AuthKit to implement authentication for an MCP server you develop. As part of that, you’ll enable CIMD in the WorkOS Dashboard under _Connect_ → _Configuration_.

## Client ID

The client ID is a public identifier for your application that maps to a specific WorkOS environment.

## Client Secret

The client secret is a value only known to your application and an OAuth identity provider. Currently, client secrets are used in OpenID Connect and Google/Microsoft/GitHub OAuth connections.

## Connection

A connection is a way for a group of users (typically in a single organization) to sign in to your application.

A directory connection is a way to retrieve a complete list of users and groups from an organization.



## Discovery Endpoint

An OIDC discovery endpoint is a URL that provides metadata about an OIDC provider, including the issuer URL, supported authentication and token endpoints, supported scopes, public keys for signature verification, and other configuration information.

The discovery endpoint path is `/.well-known/openid-configuration` on a URL.

Clients can use this endpoint to dynamically discover and interact with an OIDC provider without requiring manual configuration.

## Directory Group

A directory group is a collection of users within an organization who have been provisioned with access to your application.

## Directory Provider

A directory provider is the source of truth for your enterprise client’s user and group lists.

## Directory User

A directory user is a person or entity within an organization who has been provisioned access to your application.



## Endpoint

An endpoint is a location where an API receives requests about a specific resource.

In the context of a Directory Sync integration, an endpoint is the standardized SCIM definition of two things: a `/Users` endpoint and a `/Groups` endpoint.



## HRIS

A Human Resources Information System (HRIS) is software designed to maintain, manage, and process detailed employee information and human resources-related policies.



## IdP

An Identity Provider (IdP) is the source of truth for your enterprise client’s user database and authentication. Sometimes referred when describing the IdP-initiated flow, which is an authentication flow that starts from an identity provider like Okta instead of your application.

## IdP URI (Entity ID)

An Identity Provider URI (Entity ID) is a globally unique name for an identity provider that performs SAML authentication assertions. Sometimes referred to as Identity Provider Issuer (Okta, Entra ID).

## IdP SSO URL

An Identity Provider SSO URL (IdP SSO) is the URL your application’s users will be redirected to for authentication with an identity provider. Sometimes referred to as Identity Provider SAML 2.0 Endpoint (OneLogin).

## IdP Metadata

An Identity Provider Metadata (IdP Metadata) is the URL or XML file containing all of the metadata relevant to a specific identity provider. It includes attributes used by a service provider to route SAML messages, which minimizes the possibility of a rogue identity provider orchestrating a man-in-the-middle attack.



## JIT User Provisioning

Just-in-time (JIT) user provisioning creates a user in an app when the user attempts to sign in for the first time. The account and respective role doesn’t exist until the user creates it – just-in-time.

## JWT

JSON Web Tokens are an open, industry standard method for representing claims securely between two parties.



## Logout redirect

An allowlisted location a user will be redirected to after their session has been ended by the Logout API.

## OAuth 2.0

OAuth 2.0 is an open standard for authorization. WorkOS supports OAuth 2.0, and our Single Sign-On API is modeled after concepts found in OAuth.

## OIDC

OpenID Connect (OIDC) is an open standard and identity layer built on top of the OAuth 2.0 framework.



## Redirect URI

A redirect URI is a required, allowlisted callback URL. The redirect URI indicates the location to return an authorized user to after an authorization code is granted, and the authentication process is complete.



## SAML

Security Assertion Markup Language (SAML) is an open standard for authentication. Most of your enterprise clients will require SAML 2.0 authentication for their Single Sign-On.

## SCIM

System for Cross-domain Identity Management (SCIM) is an open standard for managing automated user and group provisioning. It’s a standard that many directory providers interface with.

## SP

Service Provider (SP) is SAML parlance for “your application”. Sometimes referred when describing the SP-initiated flow, which is an authentication flow that starts from your application instead of an identity provider like Okta.

## SP Entity ID

A Service Provider (SP) Entity ID is a globally unique name for a service provider that performs SAML authentication requests, and is the intended audience for SAML responses. It is sometimes referred to as the Audience value.

## SP Metadata

Service Provider Metadata (SP Metadata) is an XML file containing all of the metadata relevant to a specific service provider. Identity providers will use SP metadata files to make onboarding your application easier.



## TOTP

Time-based One-time Password (TOTP) is a temporary code, generated by an algorithm that uses the current time as a source of uniqueness.



## X.509 Certificate

An X.509 Certificate is a public key certificate used to authenticate SAML assertions. Sometimes referred to as Token Signature (AD FS).


## Email {#email}

### Email delivery

Best practices for sending email with WorkOS.

## Introduction

Many WorkOS features rely on your users receiving and acting upon email. For example, this includes invitations to join your app, password reset links, or Magic Auth sign-in. Prompt delivery of these emails is crucial.

WorkOS offers three options for sending email:

- **WorkOS email domain:** WorkOS sends email from the `workos-mail.com` domain.
- **Your email domain:** WorkOS sends email from your own email domain.
- **Send your own email:** WorkOS emits events, allowing your app to listen to these events and send email using your own email provider.

These options provide different trade-offs between convenience, customization, and control over email deliverability.

WorkOS follows industry best practices when sending email. SPF and DKIM email authentication records are configured automatically, the email content is continually refined to ensure it passes spam filters, and delivery of every email is actively monitored. However, regardless of the option you chose for sending email to your users, there are additional steps you can take to ensure that it reaches user inboxes.

---

## (A) WorkOS email domain

By default WorkOS will send the following emails from the `workos-mail.com` domain in production environments.

| Email              | Sent From               | Purpose                                |
| ------------------ | :---------------------- | :------------------------------------- |
| Invitation         | welcome@workos-mail.com | Invite a user to create an account     |
| Magic Auth         | access@workos-mail.com  | Allow sign in with a one-time-use code |
| Email verification | welcome@workos-mail.com | Verify ownership of a given email      |
| Password reset     | access@workos-mail.com  | Support the password reset flow        |

WorkOS has configured SPF, DKIM and DMARC email authentication records for the `workos-mail.com` domain. These records prove to the receiving mail server that a given email comes from WorkOS.

We actively monitor the delivery of email sent from the `workos-mail.com` domain to protect the domain's reputation. If we detect unusually high rates of undelivered mail or mail marked as spam from a WorkOS team account, we may suspend that team's ability to send email.

### Do not send unsolicited email

To ensure email is delivered when using the WorkOS email domain, be sure not to allow unsolicited email to be sent on your behalf. For example, an invitation email should be sent only if a user explicitly requests access to your application for themselves or another user. Do not attempt to bulk invite users from an email marketing list.

### Use appropriate team and organization names

It is also important to ensure that your WorkOS team account and all organizations under your team have appropriate names that avoid [common spam words](https://mailtrap.io/blog/email-spam-words/) that may trigger spam filters. While our static email content is thoroughly tested, WorkOS emails can include your team name as well as the names of organizations under your team. There may be an impact to email deliverability if these names use terms often flagged by spam filters.

---

## (B) Your email domain

While using the WorkOS email domain option is convenient, you can provide your users a better experience. Using your own email domain means that your users will receive emails from a domain they recognize, one associated with your app. In addition, because you control the email domain, you have more control over the domain reputation and therefore more control over email deliverability.

You can configure your own email domain in the [WorkOS dashboard](https://dashboard.workos.com). You will need to verify ownership of the domain by setting up a CNAME record with your domain provider. Two additional CNAME records are required to automatically configure SPF and DKIM email authentication using [SendGrid's automated security feature](https://support.sendgrid.com/hc/en-us/articles/21415314709147-Email-Authentication-SendGrid-s-Automated-Security-Explained).

![Configuring your email domain](https://images.workoscdn.com/images/84e47c58-e5e5-47c3-8245-f414a203f284.png?auto=format&fit=clip&q=50)

In addition to not sending unsolicited emails and using appropriate team and organization names, when using your own email domain there are a few additional steps you can take to ensure email is delivered promptly.

### Set up inboxes

When using your own domain, email will be sent from `welcome@` and `access@`. Email providers check if there are inboxes associated with sender addresses, so setting up inboxes for both the `welcome` and `access` email addresses on your domain can help ensure your emails reach users.

### Set up DMARC

WorkOS recommends that you set up DMARC (Domain-based Message Authentication, Reporting & Conformance) with your domain provider. Google has released [guidelines](https://support.google.com/a/answer/81126?visit_id=638529785140327067-2643207201&rd=1#zippy=%2Crequirements-for-all-senders%2Crequirements-for-sending-or-more-messages-per-day) for email senders and the guidelines include DMARC requirements. Apple and Yahoo have released similar best practice guides.

A DMARC policy tells a receiving mail server what to do when a message from your domain doesn’t pass DMARC authentication. Configuring DMARC requires setting up a DNS TXT record with your domain provider.

Here is an example DMARC record that will reject all emails not legitimately sent by an email provider on your behalf:

```plaintext
TXT Record

name:
_dmarc<.example.com>

content:
v=DMARC1; p=reject; rua=mailto:postmaster@example.com, mailto:dmarc@example.com; pct=100; adkim=s; aspf=s
```

More details about DMARC can be found at [dmarc.org](https://dmarc.org/overview/).

---

## (C) Connect your own email provider to WorkOS

By connecting your own email provider to WorkOS, you get control over deliverability, reputation, and compliance, while still offloading the heavy lifting of email handling. This option also allows you to easily utilize an existing email service provider configuration.

For complete instructions on configuring a custom email provider, see the [custom email providers section](/authkit/custom-email-providers).

---

## (D) Send your own email

There are a number of reasons why you may want to send email using your own email provider. Perhaps you already send a welcome email to new users and want to include an invitation link instead of sending a second email. Perhaps you already track sent email status with your own email provider and want a unified view into the status of all emails associated with your app. Regardless, when you send your own email, you have complete control over email deliverability.

For complete instructions on sending your own email, see the section on [custom emails](/authkit/custom-emails) in the AuthKit documentation.

When sending your own email, you will want to follow the all of the recommendations in Google's [email sender guidelines](https://support.google.com/a/answer/81126?hl=en). This includes setting up SPF, DKIM and DMARC email authentication.

You will also need to be conscious of your sender reputation. It's based on the quality of emails, their frequency, and user interaction. A good sender reputation can increase the chances of your emails reaching inboxes. SendGrid provides some [useful tips for improving sender reputation](https://sendgrid.com/en-us/blog/email-reputation-101-ip-reputation-vs-domain-reputation).

If you author your own email content, you may want to test your emails against various email providers' spam filters. There are a number of spam testing services available such as [Litmus](https://www.litmus.com/email-testing) and [Warmly](https://www.warmy.io/free-tools/email-deliverability-test/).

---

## Troubleshooting

Even when following industry best practices, an email may get filtered as spam and not reach a user's inbox. Other times an email might be delayed, for example, when [Enhanced Pre-delivery Message Scanning](https://apps.google.com/supportwidget/articlehome?hl=en&article_url=https%3A%2F%2Fsupport.google.com%2Fa%2Fanswer%2F7380368%3Fhl%3Den&product_context=7380368&product_name=UnuFlow&trigger_context=a) is enabled on a Google workspace or when a similar feature is enabled with other email providers. Email providers do not explain the heuristics used by their spam filters and security mechanisms, and they are often changing, making it especially frustrating to troubleshoot problems.

The first step in troubleshooting is to determine if the problem exists for all users or only a subset of users. Generally, this will provide insight into the nature of the issue and how best to resolve it. If the issue exists for all users, it is most likely a matter of poor domain reputation. If the issue only exists for a subset of users, it may be because of specific settings used by an email provider or the IT department at a given organization.

Both Google and Microsoft have been noted as being especially aggressive when identifying spam. However, both companies provide some tooling to help you debug email deliverability problems. Google offers [Postmaster Tools](https://www.gmail.com/postmaster/) to help with email deliverability related to Gmail and Google Workspaces. Microsoft offers similar tools with [Sender Support](https://sendersupport.olc.protection.outlook.com/pm/). Lastly, more general spam testing services such as [Litmus](https://www.litmus.com/email-testing) and [Warmly](https://www.warmy.io/free-tools/email-deliverability-test/) are available.

If you continue to have issues regarding email deliverability despite following all of the above suggestions, please [contact support](mailto:support@workos.com).


## Widgets {#widgets}

### User Sessions Widget

A widget for displaying and managing user sessions in your application.

The `` widget provides users with visibility into their active sessions across different devices and browsers. Users can view session details and sign out of individual sessions as needed. No special permissions are required to use this widget.



## API Reference

### User Security Widget

A widget for controlling user security settings in your application.

The `` widget enables users to control their security settings. With this widget, users can:

- Set or change their password
- Configure and reset Multi-Factor Authentication

No special permissions are required to use this widget.



## API Reference

### User Profile Widget

A widget for displaying and managing a user’s profile in your application.

The `` widget allows users to view and manage their personal information.
Users can see their profile details and edit their display name.
This widget provides a simple, user-friendly interface for basic profile management.

No special permissions are required to use this widget.



## API Reference

### User Management Widget

A widget for displaying and managing users in your application.

![Users Management screenshot](https://images.workoscdn.com/images/20f235c5-c888-48f5-90aa-87ec9189483a.png?auto=format&fit=clip&q=50)

The `` widget allows an organization admin to manage the members in an organization. Admins can invite new users, remove users, and change roles all within the widget.

In order to use the User Management widget, a user must have a role that has the `widgets:users-table:manage` permission.



## API Reference

### Authorization Tokens

Ensure Widgets have the appropriate permissions in your application.

Widgets must be supplied with an authorization token. The token can be acquired in one of two ways:

- If you are using the `authkit-js` or `authkit-react` libraries, you can use the provided access token.
- If you use one of our backend SDKs, use the "get token" method in the SDK to request a token with the appropriate scope for the widget you want to use. Widget tokens expire after one hour.



> New WorkOS accounts are created with an "Admin" role that has all Widget permissions assigned. Existing accounts will need to assign the proper permissions to a role. This can be done on the "Roles" page of the WorkOS Dashboard. See the [Roles and Permissions guide](/authkit/roles-and-permissions) for more information.

To successfully generate a token, the user must be assigned a role with the correct permissions for the widget.

### Quick Start

A step-by-step guide for setting up WorkOS Widgets in your application.

## Installation

First, install the `@workos-inc/widgets` package from the npm registry, along with its peer dependencies:

```bash title="Install packages"
npm install @workos-inc/widgets @radix-ui/themes @tanstack/react-query
```

WorkOS Widgets uses [Radix Themes](https://www.radix-ui.com/themes) for its UI components and style customization APIs, while [TanStack Query](https://tanstack.com/query/latest) is used for data fetching and caching. Since both libraries are often used in applications, we require them as peer dependencies to avoid duplication, version conflicts, and bloated bundles.

> Widgets can be used in any client- or server-rendered React application. See our [Widgets examples on GitHub](https://github.com/workos/widgets-examples) to see how they can be integrated in various frameworks.

## Styles

WorkOS Widgets are powered by Radix Themes, which provides beautiful default styles with zero configuration. Start by importing styles exported from both Radix Themes and WorkOS Widgets.



> Widgets can be customized using the `theme` prop or with plain CSS. See the [styling guide](/widgets/styling) for more details.

## Root component

The `WorkOsWidgets` component should be rendered at the top of your application. This component is responsible for managing context for data fetching and providing theme styles to all Widgets.



## CORS configuration

Because WorkOS widgets issue client-side requests to WorkOS, it is necessary to configure your site as an allowed web origin. Adding this in the [Authentication section of the dashboard](https://dashboard.workos.com/) will prevent CORS issues when using the widget.

![CORS configuration](https://images.workoscdn.com/images/deb27664-e2e1-4c3b-afa1-e8ba2578c77c.png?auto=format&fit=clip&q=50)

### Pipes Widget

A widget for displaying and managing connected accounts with Pipes.

![Pipes widget screenshot](https://images.workoscdn.com/images/e84a33bb-0510-4d85-9041-33b1a0ce938c.png?auto=format&fit=clip&q=50)

The `` widget allows users to manage their connections to third-party
providers. Users can view the available providers, connect their
accounts, reauthorize when needed, and disconnect
their accounts.

Read more in the [Pipes guide](/pipes).



## API Reference

### Organization Switcher Widget

A widget for switching between organizations in your application.

The `` widget allows users to switch between organizations. There are no special permissions required to use this widget as users can switch between organizations they have access to. If an organization requires SSO or MFA, the user will be redirected to reauthorize with the new organization.

![Organization Switcher screenshot](https://images.workoscdn.com/images/e22cad7a-f11a-4f47-8cc7-fb015a22114f.png?auto=format&fit=clip&q=80)

### Switching Organizations

There are multiple ways to integrate with the Organization Switcher widget depending on your library choice. If you are using either the `authkit-js` or `authkit-react` libraries, you can use the `useAuth` hook to get the current organization and pass it to the widget.



If you are using one of the backend SDKs, you can build the organization switcher action in the backend and pass it in as a prop to the widget to be called when the user attempts to switch organizations. See the [Switching Organizations](/authkit/sessions/integrating-sessions/switching-organizations) guide for more information to set up the backend actions. This can then be passed in as a prop to the widget.



### Creating Organizations

The widget accepts children components that can be used to either redirect the user to create an organization or to show a modal with a form to create an organization. You can use this to integrate with your existing organization creation flow that uses the WorkOS APIs to create organizations.



## API Reference

### WorkOS Widgets

Learn how to integrate WorkOS Widgets in your app.

## Introduction

WorkOS Widgets are React components that provide complete functionality for common enterprise app workflows, for example a Users Management Widget that provides a UI for inviting, removing and editing users.

This guide will cover how to add a widget to your app, configure CORS, and supply an authorization token for the widget.

### API Keys Widget

A widget for displaying and managing API Keys.

![API Keys widget screenshot](https://images.workoscdn.com/images/13e0893f-eb84-43f1-9467-2598567538f3.png?auto=format&fit=clip&q=50)

The `` widget allows an admin to manage API keys in an organization. Admins can create API keys with specific permissions, view details of existing API keys, and revoke API keys, all within the widget.

In order to use the API Keys widget, a user must have a role that has the `widgets:api-keys:manage` permission.



## API Reference

### SSO Connection Widget

A widget for setting up SSO connections in the Admin Portal.

The `` widget enables users to set up SSO connections in the Admin Portal.

In order to use the SSO Connection widget, a user must have a role that has the `widgets:sso:manage` permission.



## API Reference

### Domain Verification Widget

A widget for verifying domains in the Admin Portal.

The `` widget enables users to verify domains in the Admin Portal.

In order to use the Domain Verification widget, a user must have a role that has the `widgets:domain-verification:manage` permission.



## API Reference

### Theme Customization

Customize the look and feel of WorkOS Widgets using Radix Themes.

## Using the `theme` prop

The `theme` prop can be used to customize the overall appearance of WorkOS Widgets.

`theme` support relies on external stylesheets from Radix Themes and WorkOS Widgets. Start by importing both stylesheets into your application.



### `theme` properties



See the [Radix Themes API reference](https://www.radix-ui.com/themes/docs/components/theme#api-reference) for more information on theming options.

## Using the `elements` prop

Underlying components can be styled using the `elements` prop. This object is a mapping of component names to their respective Radix Theme component props.



### `elements` properties

Each element is mapped to a Radix Theme component and accepts the same props as its respective component. See the Radix Themes documentation for each component for all available props.

| Component             | Radix component                                                             |
| :-------------------- | :-------------------------------------------------------------------------- |
| `avatar`              | [`Avatar`](https://www.radix-ui.com/themes/docs/components/avatar)          |
| `badge`               | [`Badge`](https://www.radix-ui.com/themes/docs/components/badge)            |
| `primaryButton`       | [`Button`](https://www.radix-ui.com/themes/docs/components/button)          |
| `secondaryButton`     | [`Button`](https://www.radix-ui.com/themes/docs/components/button)          |
| `destructiveButton`   | [`Button`](https://www.radix-ui.com/themes/docs/components/button)          |
| `dialog`              | [`Dialog`](https://www.radix-ui.com/themes/docs/components/dialog)          |
| `dropdown`            | [`Dropdown`](https://www.radix-ui.com/themes/docs/components/dropdown)      |
| `iconButton`          | [`IconButton`](https://www.radix-ui.com/themes/docs/components/icon-button) |
| `label`               | [`Label`](https://www.radix-ui.com/themes/docs/components/label)            |
| `primaryMenuItem`     | [`MenuItem`](https://www.radix-ui.com/themes/docs/components/menu-item)     |
| `destructiveMenuItem` | [`MenuItem`](https://www.radix-ui.com/themes/docs/components/menu-item)     |
| `select`              | [`Select`](https://www.radix-ui.com/themes/docs/components/select)          |
| `skeleton`            | [`Skeleton`](https://www.radix-ui.com/themes/docs/components/skeleton)      |
| `textfield`           | [`TextField`](https://www.radix-ui.com/themes/docs/components/text-field)   |

### Styling

Customize the look and feel of WorkOS Widgets.

WorkOS Widgets are powered by Radix Themes, which provides beautiful default styles with zero configuration. The fastest way to style your Widgets is with the [`theme` prop](/widgets/styling/theme-customization).

This prop is provided to the `WorkOsWidgets` component rendered at the top of your application. All Widgets will inherit styles configured in the `theme` prop.



See the [theme customization guide](/widgets/styling/theme-customization) for more details on `theme` prop.

## Using CSS

If you choose not to use the theming capabilities in Radix Themes, you can style Widgets using CSS. Individual elements in Widgets are accessible via CSS class selectors prefixed with `woswidgets-`. For example, you can add your own button styles by selecting the `woswidgets-button` class.



See the [CSS customization guide](/widgets/styling/css-customization) for more details on styling Widgets with CSS.

### CSS Customization

Customize the look and feel of WorkOS Widgets using CSS.

Widgets can be styled using plain CSS using namespaced class and data-attribute selectors.

While optional, we recommend starting with the `layout.css` stylesheet from Radix Themes, as well as the `base.css` stylesheet from WorkOS Widgets. These styles provide a base level of functional styling without opinionated design choices.



## Universal selectors

Elements in Widgets are accessible via CSS class selectors prefixed with `woswidgets-`.

| Selector             | Description                                         |
| :------------------- | :-------------------------------------------------- |
| `.woswidgets-root`   | The root element for the Widgets provider           |
| `.woswidgets-widget` | A selector used on the root element for all Widgets |

## Element selectors

### Avatar

| Selector             | Description                 |
| :------------------- | :-------------------------- |
| `.woswidgets-avatar` | Targets all avatar elements |

### Badge

| Selector            | Description                |
| :------------------ | :------------------------- |
| `.woswidgets-badge` | Targets all badge elements |

### Button

| Selector                          | Description                 |
| :-------------------------------- | :-------------------------- |
| `.woswidgets-button`              | Targets all button elements |
| `.woswidgets-button--primary`     | Targets primary buttons     |
| `.woswidgets-button--secondary`   | Targets secondary buttons   |
| `.woswidgets-button--destructive` | Targets destructive buttons |

### Dialog

| Selector                     | Description                              |
| :--------------------------- | :--------------------------------------- |
| `.woswidgets-dialog`         | Targets all dialog elements              |
| `.woswidgets-dialog-overlay` | Targets the overlay for a dialog element |

### Dropdown

| Selector               | Description                   |
| :--------------------- | :---------------------------- |
| `.woswidgets-dropdown` | Targets all dropdown elements |

### Icon Button

| Selector                  | Description                      |
| :------------------------ | :------------------------------- |
| `.woswidgets-button`      | Targets all button elements      |
| `.woswidgets-icon-button` | Targets all icon button elements |

### Label

| Selector            | Description                |
| :------------------ | :------------------------- |
| `.woswidgets-label` | Targets all label elements |

### Menu Item

| Selector                             | Description                    |
| :----------------------------------- | :----------------------------- |
| `.woswidgets-menu-item`              | Targets all menu item elements |
| `.woswidgets-menu-item--destructive` | Targets destructive menu items |

### Select

| Selector                      | Description                                      |
| :---------------------------- | :----------------------------------------------- |
| `.woswidgets-select`          | Targets all select elements                      |
| `.woswidgets-select-dropdown` | Targets dropdown elements belonging to a select  |
| `.woswidgets-select-item`     | Targets menu item elements belonging to a select |

### Skeleton

| Selector               | Description                   |
| :--------------------- | :---------------------------- |
| `.woswidgets-skeleton` | Targets all skeleton elements |

### Text Field

| Selector                 | Description                     |
| :----------------------- | :------------------------------ |
| `.woswidgets-text-field` | Targets all text field elements |


## Vault {#vault}

### Quick Start

A step-by-step guide on how to start using Vault to manage encrypted objects.

## Before getting started

To get the most out of these guides, you’ll need:

- A [WorkOS account](https://dashboard.workos.com/)

Sign in to your WorkOS Dashboard account and create a new Organization.

![WorkOS Dashboard UI showing organization creation](https://images.workoscdn.com/images/1c69fd98-01be-491d-9255-58363bc6a983.png?auto=format&fit=clip&q=50)

## What you'll build

In this guide, we will walk you through what you will need to set up Vault for securing and isolating organization-specific data:

- Encrypt and store data linked to an organization
- Retrieve the encrypted data
- Delete an object that's no longer in use

## API object definitions

[Object](/reference/vault/object)
: Represents an encrypted key-value item stored by Vault.

[Organization](/reference/organization)
: Describes an organization whose users sign in with a SSO Connection, or whose users are synced with a Directory Sync Connection.

## Add Vault to your app

### Install the WorkOS SDK

WorkOS offers native SDKs in several popular programming languages. Choose a language below to see instructions in your application’s language.



### Set objects

To make calls to WorkOS, provide the API key and, in some cases, the client ID. Store these values as managed secrets, such as `WORKOS_API_KEY` and `WORKOS_CLIENT_ID`, and pass them to the SDKs either as environment variables or directly in your app's configuration based on your preferences.

```plain title="Environment variables"
WORKOS_API_KEY='sk_example_123456789'
WORKOS_CLIENT_ID='client_123456789'
```

> The code examples use your staging API keys when [signed in](https://dashboard.workos.com)

### Create an object

The Vault API and SDKs provide a method to encrypt and store a blob of data linked to a WorkOS organization. The encryption key used will be both unique to the KV item and cryptographically isolated from all other organizations.



### Update the value of the object

Once created, the key context for an object cannot be changed. Only the value can be updated. The expected version of the object can be provided as a consistency lock when writing to the object.



### Retrieve the object value

Objects can be listed, returning just the names of the objects. The metadata for each object can be queried - this provides more information about it without needing to decrypt the actual value. Fetching the object value will return the same metadata in addition to the unencrypted value.



### Delete the object

When an object is no longer needed it can be marked for deletion. This will make the object unavailable to API operations, but the data will not be immediately deleted.

### Key Context

User-managed cardinality for keys within Vault.

When encrypting data with Vault, a set of key-value metadata pairs called the key context is required. This determines which key or keys will be used to encrypt the data without needing to explicitly list IDs for the keys. The key context is used both when [creating an encrypted object](/reference/vault/object/create) and when [encrypting locally](/reference/vault/key/encrypt-data) with Vault-managed keys.

## Key matching

Each item in the context is used to identify a long-lived key within the WorkOS environment called a key-encrypting key (KEK). The key material lives in a Hardware Security Module (HSM) and cannot be exported to plaintext - it can only be used to generate or decrypt data keys.
KEKs are created just-in-time and don't require any configuration in advance.

### Bring Your Own Key (BYOK)

When Vault is used with a BYOK setup, the customer-managed key (CMK) is used in place of the WorkOS managed KEK. Matching the encryption operation to the CMK is still done based on the key context.

For example, if Vault is configured to use a CMK called `key_abc` for all data of `organization_abc123`, then that key would automatically be used when the key context is set to `{"organization_id": "organization_abc123"}`. The same operation with a context of `{"organization_id": "organization_xzy987"}` would instead use a WorkOS managed KEK.

## Data keys

Although the KEKs identified by key context are long-lived, they aren't directly used for encrypting data. A random data-encrypting key (DEK) is generated for an encryption operation. The DEK is then encrypted using each KEK from the key context, resulting in a single plaintext key and one or more encrypted keys. The encrypted keys are then stored with the encrypted data for future decryption. This ensures that the data and keys have the same durability while keeping the keys safe. It also means that even if one key is exposed, not all of the data will be at risk since many different data keys are used for the same key context.

## Limitations

The following limitations are enforced by the Vault API for the key context object:

- All values in the context must be strings.
- A maximum of 10 items can be present in a single context.
- Each context name has a maximum length of 120 characters.
- Each context value has a maximum length of 500 characters.

### Vault

Encrypt, store, and control access to sensitive data.