API Reference

Section titled API Reference

The WorkOS API enables adding Enterprise Ready features to your application. This REST API provides programmatic access and management of SSO, Magic Link, Directory Sync, and Audit Trail resources.

API Base URL

 https://api.workos.com

Client Libraries

Section titled Client Libraries

WorkOS offers native SDKs in several popular programming languages. Choose one language below to see our API Reference in your application’s language.

API Keys

Section titled API Keys

WorkOS authenticates your API requests using your account’s API keys. API requests made without authentication or using an incorrect key will return a 401 error. Requests using a valid key but with insufficient permissions will return a 403 error. All API requests must be made over HTTPS. Any requests made over plain HTTP will fail.

Set API Key

 curl https://api.workos.com/directories \
  --header "Authorization: Bearer sk_example_123456789"

You can view and manage your API keys in the WorkOS Dashboard.

Secure your API Keys

API keys can perform any API request to WorkOS. They should be kept secure and private! Be sure to prevent API keys from being made publicly accessible, such as in client-side code, GitHub, unsecured S3 buckets, and so forth. API keys are prefixed with sk_.

In Staging

Your Staging Environment comes with an API key already generated for you. Staging API keys may be viewed as often as they are needed and will appear inline throughout our documentation in code examples if you are logged in to your WorkOS account. API requests will be scoped to the provided key’s Environment.

In Production

Once you unlock Production access you will need to generate an API Key for it. Production API keys may only be viewed once and will need to be saved in a secure location upon creation of them.

Errors

Section titled Errors

WorkOS uses standard HTTP response codes to indicate the success or failure of your API requests.

200: Successful request.
400: The request was not acceptable. Check that the parameters were correct.
401: The API key used was invalid.
403: The API key used did not have the correct permissions.
404: The resource was not found.
5xx: Indicates an error with WorkOS servers.

Pagination

Section titled Pagination

Many top-level resources have support for bulk fetches via “list” API methods. For instance, you can list connections, list directory users, and list directory groups. These list API methods share a common structure, taking at least these four parameters: limit, order, after, and before.

WorkOS utilizes pagination via the after and before parameters. Both parameters take an existing object ID value (see below) and return objects in either descending or ascending order by created_at timestamp.

Response with List Metadata

cURL

 {
  "data": [
    {
      "object": "connection",
      "id": "conn_01E4ZCR3C56J083X43JQXF3JK5",
      "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
      "connection_type": "GoogleOAuth",
      "name": "Foo Corp",
      "state": "active",
      "created_at": "2021-06-25T19:07:33.155Z",
      "updated_at": "2021-06-25T19:08:33.155Z"
    },
    {
      "object": "connection",
      "id": "conn_01E2NPPCT7XQ2MVVYDHWGK1WN4",
      "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
      "connection_type": "OktaSAML",
      "name": "Example Co",
      "state": "active",
      "created_at": "2021-06-25T19:09:33.155Z",
      "updated_at": "2021-06-25T19:10:33.155Z"
    }
  ],
  "list_metadata": {
    "before": "conn_01E2NPPCT7XQ2MVVYDHWGK1WN4",
    "after": null
  }
}

Webhooks

Section titled Webhooks

WorkOS uses webhooks to automatically notify your application any time certain changes are made to your Connections.

A webhook URL is an endpoint hosted by your application that subscribes to notifications from WorkOS. WorkOS sends these notifications as Events which detail changes to users and groups. Each time there is a change, WorkOS makes a request to your application’s webhook URL containing an Event. You’ll receive an Event when new users are created, group properties are updated, or users have been added to a group, to name a few examples. Each Event contains specific information explaining what happened to trigger the webhook.

Idempotency

Section titled Idempotency

The WorkOS API supports idempotency which guarantees that performing the same operation multiple times will have the same result as if the operation were performed only once. This is handy in situations where you may need to retry a request due to a failure or prevent accidental duplicate requests from creating more than one resource.

To achieve idempotency, you can add Idempotency-Key request header to any WorkOS API request with a unique string as the value. Each subsequent request matching this unique string will return the same response. We suggest using v4 UUIDs for idempotency keys to avoid collisions.

Idempotency Key Example

cURL

 curl --request POST \
  --url https://api.workos.com/organizations \
  -H "Authorization: Bearer sk_example_123456789" \
  -H "Idempotency-Key: cd320c5c-e928-4212-a5bd-986c29362867" \
  -d 'name="Foo Corp"' \
  -d 'domains[]="foo-corp.com"'

Idempotency keys expire after 24 hours. The WorkOS API will generate a new response if you submit a request with an expired key.

Organization

Section titled Organization

An Organization is a top-level resource in WorkOS. Each Connection, Directory, and Audit Trail Event belongs to an Organization. An Organization will usually represent one of your customers.

Organizations can optionally have Organization Domains which are useful to tag any domains that used across all associated Connections and Directories.

Example Organization

 {
  "object": "organization",
  "id": "org_01EHZNVPK3SFK441A1RGBFSHRT",
  "name": "Foo Corp",
  "allow_profiles_outside_organization": false,
  "created_at": "2021-06-25T19:07:33.155Z",
  "updated_at": "2021-06-25T19:07:33.155Z",
  "domains": [
    {
      "id": "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A",
      "object": "organization_domain",
      "domain": "foo-corp.com"
    }
  ]
}

`organization`

Distinguishes the Organization object.

Unique identifier of the Organization.

A descriptive name for the Organization. This field does not need to be unique.

Whether the Connections within this Organization should allow Profiles that do not have a domain that is present in the set of the Organization’s User Email Domains.

The timestamp when the Organization was last created.

The timestamp when the Organization was last updated.

List of Organization Domains.

Get an Organization

Section titled Get an Organization

Get the details of an existing organization.

Request

 curl https://api.workos.com/organizations/org_01EHZNVPK3SFK441A1RGBFSHRT \
  --header "Authorization: Bearer sk_example_123456789"

 {
  "id": "org_01EHZNVPK3SFK441A1RGBFSHRT",
  "object": "organization",
  "name": "Foo Corporation",
  "allow_profiles_outside_organization": false,
  "created_at": "2021-06-25T19:07:33.155Z",
  "updated_at": "2021-06-25T19:07:33.155Z",
  "domains": [
    {
      "domain": "foo-corp.com",
      "id": "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A",
      "object": "organization_domain"
    },
    {
      "domain": "another-foo-corp-domain.com",
      "id": "org_domain_01EHZNS0H9W90A90FV79GAB6AB",
      "object": "organization_domain"
    }
  ]
}

`GET/organizations/:id`

`Parameters`

Unique identifier of the Organization.

`Returns`

organization

List Organizations

Section titled List Organizations

Get a list of all of your existing organizations matching the criteria specified.

Request

 curl https://api.workos.com/organizations?domains=foo-corp.com \
  --header "Authorization: Bearer sk_example_123456789"

 {
  "data": [
    {
      "id": "org_01EHZNVPK3SFK441A1RGBFSHRT",
      "object": "organization",
      "name": "Foo Corp",
      "allow_profiles_outside_organization": false,
      "created_at": "2021-06-25T19:07:33.155Z",
      "updated_at": "2021-06-25T19:07:33.155Z",
      "domains": [
        {
          "domain": "foo-corp.com",
          "id": "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A",
          "object": "organization_domain"
        },
        {
          "domain": "another-foo-corp-domain.com",
          "id": "org_domain_01EHZNS0H9W90A90FV79GAB6AB",
          "object": "organization_domain"
        }
      ]
    }
  ],
  "list_metadata": {
    "before": "org_01EHZNVPK3SFK441A1RGBFSHRT",
    "after": "org_01EJBGJT2PC6638TN5Y380M40Z"
  }
}

`GET/organizations`

`Parameters`

The domains of an Organization. Any Organization with a matching domain will be returned.

Upper limit on the number of objects to return, between 1 and 100. The default value is 10.

A cursor to use for pagination. before is an object ID that defines your place in the list. For example, if you make a list request and receive 100 objects, ending with obj_123, your subsequent call can include before=obj_123 to fetch a new batch of objects before obj_123.

A cursor to use for pagination. after is an object ID that defines your place in the list. For example, if you make a list request and receive 100 objects, ending with obj_123, your subsequent call can include after=obj_123 to fetch a new batch of objects after obj_123.

Order the results by the created_at timestamp. Supported values are "asc" and "desc" for ascending and descending order respectively.

`Returns`

object

Array of Organizations in descending order by created_at timestamp.

Create an Organization

Section titled Create an Organization

Creates a new organization in the current environment.

Request

 curl --request POST \
  --url https://api.workos.com/organizations \
  --header "Authorization: Bearer sk_example_123456789" \
  -d name="Foo Corp" \
  -d 'domains[]="foo-corp.com"'

 {
  "id": "org_01EHZNVPK3SFK441A1RGBFSHRT",
  "object": "organization",
  "name": "Foo Corp",
  "allow_profiles_outside_organization": false,
  "created_at": "2021-06-25T19:07:33.155Z",
  "updated_at": "2021-06-25T19:07:33.155Z",
  "domains": [
    {
      "domain": "foo-corp.com",
      "id": "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A",
      "object": "organization_domain"
    },
    {
      "domain": "another-foo-corp-domain.com",
      "id": "org_domain_01EHZNS0H9W90A90FV79GAB6AB",
      "object": "organization_domain"
    }
  ]
}

`POST/organizations`

`Parameters`

A descriptive name for the Organization. This field does not need to be unique.

Whether the Connections within this Organization should allow Profiles that do not have a domain that is present in the set of the Organization’s User Email Domains.

The domains of the Organization.

At least one domain is required unless allow_profiles_outside_organization is true.

`Returns`

organization

Update an Organization

Section titled Update an Organization

Updates an organization in the current environment.

Request

 curl --request PUT \
  --url https://api.workos.com/organizations/org_01EHZNVPK3SFK441A1RGBFSHRT \
  --header "Authorization: Bearer sk_example_123456789" \
  -d name="Foo Corporation" \
  -d 'domains[]="foo-corp.com"'

 {
  "id": "org_01EHZNVPK3SFK441A1RGBFSHRT",
  "object": "organization",
  "name": "Foo Corp",
  "allow_profiles_outside_organization": false,
  "created_at": "2021-06-25T19:07:33.155Z",
  "updated_at": "2021-06-25T19:07:33.155Z",
  "domains": [
    {
      "domain": "foo-corp.com",
      "id": "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A",
      "object": "organization_domain"
    },
    {
      "domain": "another-foo-corp-domain.com",
      "id": "org_domain_01EHZNS0H9W90A90FV79GAB6AB",
      "object": "organization_domain"
    }
  ]
}

`PUT/organizations/:id`

`Parameters`

A descriptive name for the Organization. This field does not need to be unique.

Whether the Connections within this Organization should allow Profiles that do not have a domain that is present in the set of the Organization’s User Email Domains.

The domains of the Organization.

At least one domain is required unless allow_profiles_outside_organization is true.

`Returns`

organization

Delete an Organization

Section titled Delete an Organization

Deletes an organization in the current environment.

Request

 curl https://api.workos.com/organizations/org_01EHZNVPK3SFK441A1RGBFSHRT \
  --header "Authorization: Bearer sk_example_123456789"

`DELETE/organizations/:id`

`Parameters`

Unique identifier of the Organization.

Organization Domain

Section titled Organization Domain

An Organization Domain (also known as a User Email Domain) represents an Organization's domain.

These domains restrict which email addresses are able to sign in through SAML Connections when allow_profiles_outside_organization is false. This is the default behavior for Organizations. See here for more details on this behavior.

Example Organization Domain

 {
  "id": "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A",
  "object": "organization_domain",
  "domain": "foo-corp.com"
}

`organization_domain`

Distinguishes the Organization Domain object.

Unique identifier for the Organization Domain.

Domain for the Organization Domain.

Single Sign-On

Section titled Single Sign-On

The Single Sign-On API has been modeled to meet the OAuth 2.0 framework specification. As a result, authentication flows constructed using the Single Sign-On API replicate the OAuth 2.0 protocol flow.

Redirect URI

Section titled Redirect URI

In the OAuth 2.0 protocol, a redirect URI is the location your user is redirected to once they have successfully authenticated with their Identity Provider.

In Production Environments, the redirect URI to your application must use HTTPS and there should be at least one redirect URI configured and selected as a default for a WorkOS Environment. This can be done from the SSO Configuration page in the WorkOS dashboard. Without a valid redirect URI, users will be unable to sign in.

Redirect URIs that use HTTP and localhost are allowed in Sandbox Environments.

Example Redirect URI

 https://your-app.com/callback?
code=01E2RJ4C05B52KKZ8FSRDAP23J&
state=dj1kUXc0dzlXZ1hjUQ==

Get Authorization URL

Section titled Get Authorization URL

Generate an OAuth 2.0 authorization URL.

WorkOS generates an OAuth 2.0 authorization URL that automatically directs a user to their Identity Provider. Once the user authenticates with their Identity Provider, WorkOS then issues a redirect to your Redirect URI to complete the login flow.

To indicate the connection to use for authentication, use one of the following connection selectors: connection, organization, or provider.

These connection selectors are mutually exclusive, and exactly one must be provided.

Request

 curl https://api.workos.com/sso/authorize -G \
  -d response_type=code \
  -d client_id=client_123456789 \
  -d redirect_uri=https://your-app.com/callback \
  -d state=dj1kUXc0dzlXZ1hjUQ== \
  -d connection=conn_01E4ZCR3C56J083X43JQXF3JK5

 https://api.workos.com/sso/authorize?
response_type=code&
client_id=client_123456789&
redirect_uri=https://your-app.com/callback&
state=dj1kUXc0dzlXZ1hjUQ==&
connection=conn_01E4ZCR3C56J083X43JQXF3JK5

`GET/sso/authorize`

The only valid option for the response type parameter is code.

The code parameter value initiates an Authorization Code Grant Type. This grant type allows a Developer to exchange an authorization code for an access token during the redirect that takes place after a user has authenticated with an Identity Provider.

This value can be obtained from the SSO Configuration page in the WorkOS dashboard.

The connection connection selector is used to initiate SSO for a Connection.

The value of this parameter should be a WorkOS Connection ID.

For example, the Developer can persist the WorkOS Connection ID with application User or Team identifiers. WorkOS will use the Connection indicated by the connection parameter to direct the user to the corresponding IdP for authentication.

The organization connection selector is used to initiate SSO for an Organization.

The value of this parameter should be a WorkOS Organization ID.

For example, the Developer can persist the WorkOS Organization ID with application User or Team identifiers. WorkOS will use the organization connection selector to determine the appropriate Connection and IdP to direct the user to for authentication.

Note that the Organization must only have a single active SSO Connection, otherwise an ambiguous_connection_selector error code will be returned.

The provider connection selector is used to initiate SSO using an OAuth provider.

Currently, the only supported values for provider are GoogleOAuth and MicrosoftOAuth. Provide the provider parameter when authenticating Google OAuth users, because Google OAuth does not take a user’s domain into account when logging in with a “Sign in with Google” button.

Optional parameter that a Developer can choose to include in their authorization URL. If included, then the redirect URI received from WorkOS will contain the exact state that was passed in the authorization URL.

The state parameter can be used to encode arbitrary information to help restore application state between redirects.

Can be used to pre-fill the username/email address field of the IdP sign-in page for the user, if you know their username ahead of time.

Currently, this parameter is only supported for OAuth, and OpenID Connect connection types.

Can be used to pre-fill the domain field when initiating authentication with Microsoft OAuth.

`Returns`

An OAuth 2.0 authorization URL.

Error codes

If there is an issue generating an authorization URL, WorkOS will issue a redirect with an error query parameter, an error_description query parameter with additional information, and the original state parameter (if provided). Possible error codes are listed below.

ambiguous_connection_selector: A Connection could not be uniquely identified using the provided connection selector (e.g., organization). This can occur when there are multiple SSO Connections under the same Organization. If you need multiple SSO Connections for an Organization, use the connection parameter to identify which Connection to use for SSO.
connection_domain_invalid: There is no Connection for the provided domain.
connection_invalid: There is no Connection for the provided ID.
connection_strategy_invalid: The Provider has multiple strategies associated per environment.
connection_unlinked: The Connection associated with the request is unlinked.
domain_connection_selector_not_allowed: This is a legacy error code that only applies if using the deprecated “domain” query parameter which is no longer valid for the Get Authorization URL endpoint. Use the “organization” or “connection” query parameters to target a connection instead.
invalid_connection_selector: A valid connection selector query parameter must be provided in order to correctly determine the proper Connection to return an authorization URL for. Valid connection selectors are either connection, organization, or provider.
organization_invalid: There is no Organization for the provided ID.
profile_not_allowed_outside_organization: A Profile was received that has an email that is outside the Organization's User Email Domains and the Organization does not allow this. To resolve this, either add the missing domain to the Organization's User Email Domains or configure the Organization to allow profiles outside of it.

Profile

Section titled Profile

A Profile is an object that represents an authenticated user. The Profile object contains information relevant to a user in the form of normalized and raw attributes.

After receiving the Profile for an authenticated user, use the Profile object attributes to persist relevant data to your application’s user model for the specific, authenticated user.

No Profile attributes can be returned other than the normalized attributes listed below, and the raw attributes returned by an Identity Provider.

Example Profile

 {
  "object": "profile",
  "id": "prof_01DMC79VCBZ0NY2099737PSVF1",
  "connection_id": "conn_01E4ZCR3C56J083X43JQXF3JK5",
  "connection_type": "OktaSAML",
  "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
  "email": "[email protected]foo-corp.com",
  "first_name": "Todd",
  "last_name": "Rundgren",
  "idp_id": "00u1a0ufowBJlzPlk357",
  "raw_attributes": {}
}

`profile`

Distinguishes the Profile object.

Unique identifier for the user, assigned by WorkOS.

This value can be persisted to the Developer’s user model and used as a unique key for identifying a specific user.

Unique identifier for the Connection to which the Profile belongs.

The type of SSO Connection used to authenticate the user. Possible values:

ADFSSAML
Auth0SAML
AzureSAML
CASSAML
CloudflareSAML
CyberArkSAML
ClassLinkSAML
DuoSAML GenericOIDC
GenericSAML GoogleOAuth
GoogleSAML
JumpCloudSAML
KeycloakSAML
LastPassSAML
MicrosoftOAuth
MiniOrangeSAML
NetIqSAML
OktaSAML
OneLoginSAML
OracleSAML
PingFederateSAML
PingOneSAML
SalesforceSAML
SimpleSamlPhpSAML
VMwareSAML

Unique identifier for the Organization in which the Connection resides.

The user’s email address.

The user’s first name.

The user’s last name.

Unique identifier for the user, assigned by the Identity Provider. Different Identity Providers use different ID formats.

One possible use case for idp_id is associating a user’s SSO Profile with any relevant Directory Sync actions related to that user.

Object of key-value pairs containing relevant user data from the Identity Provider.

Raw attributes are an extended set of information one can expect for each user Profile. These raw attributes will vary by Identity Provider and Identity Provider configuration.

Get a Profile and Token

Section titled Get a Profile and Token

Get an access_token along with the user’s Profile using the code we passed to your Redirect URI.

Request

 curl -X POST "https://api.workos.com/sso/token" \
  -d 'client_id=client_123456789' \
  -d 'client_secret=sk_example_123456789' \
  -d 'grant_type=authorization_code' \
  -d 'code=01E2RJ4C05B52KKZ8FSRDAP23J'

 {
  "access_token": "01DMEK0J53CVMC32CK5SE0KZ8Q",
  "profile": {
    "object": "profile",
    "id": "prof_01DMC79VCBZ0NY2099737PSVF1",
    "connection_id": "conn_01E4ZCR3C56J083X43JQXF3JK5",
    "connection_type": "OktaSAML",
    "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
    "email": "[email protected]foo-corp.com",
    "first_name": "Todd",
    "last_name": "Rundgren",
    "idp_id": "00u1a0ufowBJlzPlk357",
    "raw_attributes": {}
  }
}

`POST/sso/token`

`Parameters`

This value can be obtained from the SSO Configuration page in the WorkOS dashboard.

This is the same value as the WorkOS Environment’s secret API key.

This value can be obtained from the API Keys page in the WorkOS dashboard.

The method by which your application will receive an access token. This value should be authorization_code.

The authorization value which was passed back as a query parameter in the callback to the Redirect URI.

`Returns`

object

An access token that can be exchanged for a user profile. Access tokens are one-time use and expire 10 minutes after they’re created.

The user Profile object.

Get a User Profile

Section titled Get a User Profile

Exchange an access_token for a user’s Profile. Because this profile is returned in the Get a Profile and Token endpoint your application usually does not need to call this endpoint. It is available for any authentication flows that require an additional endpoint to retrieve a user’s profile.

Request

 curl https://api.workos.com/sso/profile \
  --header "Authorization: Bearer 01DMEK0J53CVMC32CK5SE0KZ8Q"

 {
  "object": "profile",
  "id": "prof_01DMC79VCBZ0NY2099737PSVF1",
  "connection_id": "conn_01E4ZCR3C56J083X43JQXF3JK5",
  "connection_type": "OktaSAML",
  "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
  "email": "[email protected]foo-corp.com",
  "first_name": "Todd",
  "last_name": "Rundgren",
  "idp_id": "00u1a0ufowBJlzPlk357",
  "raw_attributes": {}
}

`GET/sso/profile`

`Parameters`

The authorization value which was returned along with the profile when calling the Get a Profile and Token endpoint.

`Returns`

profile

Connection

Section titled Connection

A Connection represents the relationship between WorkOS and any collection of application users. This collection of application users may include personal or enterprise Identity Providers, or passwordless authentication methods like Magic Link. As a layer of abstraction, a WorkOS Connection rests between an application and its users, separating an application from the implementation details required by specific standards like OAuth 2.0 and SAML.

Example Connection

 {
  "object": "connection",
  "id": "conn_01E4ZCR3C56J083X43JQXF3JK5",
  "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
  "connection_type": "OktaSAML",
  "name": "Foo Corp",
  "state": "active",
  "created_at": "2021-06-25T19:07:33.155Z",
  "updated_at": "2021-06-25T19:07:33.155Z",
  "domains": [
    {
      "id": "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A",
      "object": "organization_domain",
      "domain": "foo-corp.com"
    }
  ]
}

`connection`

Distinguishes the Connection object.

Unique identifier for the Connection.

Unique identifier for the Organization in which the Connection resides.

The type of SSO Connection used to authenticate a user.

One possible use case for connection_type is dynamically generating authorization URLs. Possible values:

ADFSSAML

ADPOIDC

Auth0SAML

AzureSAML

CASSAML

ClassLinkSAML

CloudflareSAML

CyberArkSAML

DuoSAML

GenericOIDC

DuoSAML

GenericSAML

GoogleOAuth

GoogleSAML

JumpCloudSAML

KeycloakSAML

LastPassSAML

MicrosoftOAuth

MiniOrangeSAML

NetIqSAML

OktaSAML

OneLoginSAML

OracleSAML

PingFederateSAML

PingOneSAML

SalesforceSAML

SimpleSamlPhpSAML

ShibbolethSAML

ShibbolethGenericSAML

VMwareSAML

A human-readable name for the Connection. This will most commonly be the Enterprise Client’s name.

Indicates whether a Connection is able to authenticate users. Possible values:

draft

active

inactive

The timestamp when the Connection was created.

The timestamp when the Connection was last updated.

List of Organization Domains.

Get a Connection

Section titled Get a Connection

Get the details of an existing connection.

Request

 curl https://api.workos.com/connections/conn_01E2NPPCT7XQ2MVVYDHWGK1WN4 \
  --header "Authorization: Bearer sk_example_123456789"

 {
  "object": "connection",
  "id": "conn_01E4ZCR3C56J083X43JQXF3JK5",
  "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
  "connection_type": "OktaSAML",
  "name": "Foo Corp",
  "state": "active",
  "created_at": "2021-06-25T19:07:33.155Z",
  "updated_at": "2021-06-25T19:07:33.155Z",
  "domains": [
    {
      "id": "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A",
      "object": "organization_domain",
      "domain": "foo-corp.com"
    }
  ]
}

`GET/connections/:id`

`Parameters`

Unique identifier for the Connection.

`Returns`

connection

List Connections

Section titled List Connections

Get a list of all of your existing connections matching the criteria specified.

Request

 curl https://api.workos.com/connections \
  --header "Authorization: Bearer sk_example_123456789"

 {
  "data": [
    {
      "object": "connection",
      "id": "conn_01E4ZCR3C56J083X43JQXF3JK5",
      "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
      "connection_type": "GoogleOAuth",
      "name": "Foo Corp",
      "state": "active",
      "created_at": "2021-06-25T19:07:33.155Z",
      "updated_at": "2021-06-25T19:08:33.155Z"
    },
    {
      "object": "connection",
      "id": "conn_01E2NPPCT7XQ2MVVYDHWGK1WN4",
      "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
      "connection_type": "OktaSAML",
      "name": "Example Co",
      "state": "active",
      "created_at": "2021-06-25T19:09:33.155Z",
      "updated_at": "2021-06-25T19:10:33.155Z"
    }
  ],
  "list_metadata": {
    "before": "conn_01E2NPPCT7XQ2MVVYDHWGK1WN4",
    "after": null
  }
}

`GET/connections`

`Parameters`

Filter Connections by their type.

Filter Connections by their associated domain.

Filter Connections by their associated organization.

Upper limit on the number of objects to return, between 1 and 100. The default value is 10.

Order the results by the created_at timestamp. Supported values are "asc" and "desc" for ascending and descending order respectively.

`Returns`

object

An array of Connections in descending order by created_at timestamp.

Delete a Connection

Section titled Delete a Connection

Delete an existing connection.

Request

 curl --request DELETE \
  --url https://api.workos.com/connections/conn_01E2NPPCT7XQ2MVVYDHWGK1WN4 \
  --header "Authorization: Bearer sk_example_123456789"

`DELETE/connections/:id`

`Parameters`

Unique identifier for the Connection.

Connection Webhooks

Section titled Connection Webhooks

Triggers when a connection has been activated, deactivated, or deleted.

Activated

 {
  "event": "connection.activated",
  "id": "wh_10FKJ843CVE8F7BXQSPFH0M53V",
  "data": {
    "object": "connection",
    "id": "conn_01EHWNC0FCBHZ3BJ7EGKYXK0E6",
    "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
    "state": "active",
    "connection_type": "OktaSAML",
    "name": "Foo Corp's Connection",
    "created_at": "2021-06-25T19:07:33.155Z",
    "updated_at": "2021-06-25T19:07:33.155Z",
    "domains": [
      {
        "id": "conn_domain_01EHWNFTAFCF3CQAE5A9Q0P1YB",
        "object": "connection_domain",
        "domain": "foo-corp.com"
      }
    ]
  }
}

 {
  "event": "connection.deactivated",
  "id": "wh_11FKJ843CVE8F7BXQSPFH0M53V",
  "data": {
    "object": "connection",
    "id": "conn_01EHWNC0FCBHZ3BJ7EGKYXK0E6",
    "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
    "state": "inactive",
    "connection_type": "OktaSAML",
    "name": "Foo Corp's Connection",
    "created_at": "2021-06-25T19:07:33.155Z",
    "updated_at": "2021-06-25T19:07:33.155Z",
    "domains": [
      {
        "id": "conn_domain_01EHWNFTAFCF3CQAE5A9Q0P1YB",
        "object": "connection_domain",
        "domain": "foo-corp.com"
      }
    ]
  }
}

 {
  "event": "connection.deleted",
  "id": "wh_12FKJ843CVE8F7BXQSPFH0M53V",
  "data": {
    "object": "connection",
    "id": "conn_01EHWNC0FCBHZ3BJ7EGKYXK0E6",
    "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
    "state": "inactive",
    "connection_type": "OktaSAML",
    "name": "Foo Corp's Connection",
    "created_at": "2021-06-25T19:07:33.155Z",
    "updated_at": "2021-06-25T19:07:33.155Z",
    "domains": [
      {
        "id": "conn_domain_01EHWNFTAFCF3CQAE5A9Q0P1YB",
        "object": "connection_domain",
        "domain": "foo-corp.com"
      }
    ]
  }
}

`connection.activated connection.deactivated connection.deleted`

The type of webhook event.

Unique identifier for the webhook.

The updated Connection.

When receiving a connection.deleted event you can ignore the connection’s state attribute, since it indicates the state before the deletion occurs.

Directory Sync

Section titled Directory Sync

Directory Sync allows you to connect with Directory Providers to inform your application of any changes in their users, groups, or access rules.

Using Directory Sync, one integration grants your application the ability to support multiple Directory Providers. Get real-time updates of any changes to your Enterprise Client’s access rules, groups, and users by integrating webhooks into your application.

Get a Directory

Section titled Get a Directory

Get the details of an existing directory.

Request

 curl https://api.workos.com/directories/directory_01ECAZ4NV9QMV47GW873HDCX74 \
  --header "Authorization: Bearer sk_example_123456789"

 {
  "id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
  "domain": "foo-corp.com",
  "name": "Foo Corp",
  "organization_id": "org_01EHZNVPK3SFK441A1RGBFSHRT",
  "state": "unlinked",
  "type": "gsuite directory",
  "created_at": "2021-06-25T19:07:33.155Z",
  "updated_at": "2021-06-25T19:07:33.155Z"
}

`GET/directory/:id`

`Parameters`

Unique identifier for the Directory.

`Returns`

directory

List Directories

Section titled List Directories

Get a list of all of your existing directories matching the criteria specified.

Request

 curl https://api.workos.com/directories?search=WorkOS \
  --header "Authorization: Bearer sk_example_123456789"

 {
  "data": [
    {
      "id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
      "domain": "foo-corp.com",
      "name": "Foo Corp",
      "organization_id": "org_01EHZNVPK3SFK441A1RGBFSHRT",
      "object": "directory",
      "state": "unlinked",
      "type": "gsuite directory",
      "created_at": "2021-06-25T19:07:33.155Z",
      "updated_at": "2021-06-25T19:08:33.155Z"
    },
    {
      "id": "directory_01E8CS3GSBEBZ1F1CZAEE3KHDG",
      "domain": "foo-corp.com",
      "external_key": "r3NDlInUnAe6i4wG",
      "name": "Foo Corp",
      "organization_id": "org_01EHZNVPK3SFK441A1RGBFPANT",
      "object": "directory",
      "state": "linked",
      "type": "okta scim v2.0",
      "created_at": "2021-06-25T19:09:33.155Z",
      "updated_at": "2021-06-25T19:10:33.155Z"
    }
  ],
  "list_metadata": {
    "after": "directory_01E1JJS84MFPPQ3G655FHTKX6Z",
    "before": "directory_01E1JJS84MFPPQ3G655FHTKX6Z"
  }
}

`GET/directories`

`Parameters`

The domain of a Directory.

Searchable text to match against Directory names.

Filter Directories by their associated organization.

Upper limit on the number of objects to return, between 1 and 100. The default value is 10.

Order the results by the created_at timestamp. Supported values are "asc" and "desc" for ascending and descending order respectively.

`Returns`

object

Array of Directories in descending order by created_at timestamp.

Delete a Directory

Section titled Delete a Directory

Delete an existing directory.

Request

 curl --request DELETE \
  --url https://api.workos.com/directories/directory_01ECAZ4NV9QMV47GW873HDCX74 \
  --header "Authorization: Bearer sk_example_123456789"

`DELETE/directories/:id`

`Parameters`

Unique identifier for the Directory.

Directory Webhooks

Section titled Directory Webhooks

Triggers when a directory has been activated, deactivated, or deleted.

Activated

 {
  "event": "dsync.activated",
  "id": "wh_01FKJ843CVE8F7BXQSPFH0M53V",
  "data": {
    "object": "directory",
    "external_key": "UWuccu6o1E0GqkYs",
    "name": "Foo Corp's Directory",
    "organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y",
    "id": "directory_01EHWNC0FCBHZ3BJ7EGKYXK0E6",
    "state": "active",
    "type": "generic scim v2.0",
    "created_at": "2021-06-25T19:07:33.155Z",
    "updated_at": "2021-06-25T19:07:33.155Z",
    "domains": [
      {
        "object": "organization_domain",
        "id": "org_domain_01EZTR5N6Y9RQKHK2E9F31KZX6",
        "domain": "foo-corp.com"
      }
    ]
  }
}

 {
  "event": "dsync.deactivated",
  "id": "wh_02FKJ843CVE8F7BXQSPFH0M53V",
  "data": {
    "object": "directory",
    "external_key": "UWuccu6o1E0GqkYs",
    "name": "Foo Corp's Directory",
    "organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y",
    "id": "directory_01EHWNC0FCBHZ3BJ7EGKYXK0E6",
    "state": "inactive",
    "type": "generic scim v2.0",
    "created_at": "2021-06-25T19:07:33.155Z",
    "updated_at": "2021-06-25T19:07:33.155Z",
    "domains": [
      {
        "object": "organization_domain",
        "id": "org_domain_01EZTR5N6Y9RQKHK2E9F31KZX6",
        "domain": "foo-corp.com"
      }
    ]
  }
}

 {
  "event": "dsync.deleted",
  "id": "wh_03FKJ843CVE8F7BXQSPFH0M53V",
  "data": {
    "object": "directory",
    "id": "directory_01EHWNC0FCBHZ3BJ7EGKYXK0E6",
    "organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y",
    "type": "generic scim v2.0",
    "state": "deleting",
    "name": "Foo Corp's Directory",
    "created_at": "2021-06-25T19:07:33.155Z",
    "updated_at": "2021-06-25T19:07:33.155Z"
  }
}

`dsync.activated dsync.deactivated dsync.deleted`

The type of webhook event.

Unique identifier for the webhook.

The updated Directory.

When receiving a dsync.deleted event you can ignore the connection’s state attribute, since it indicates the state before the deletion occurs.

Directory User

Section titled Directory User

A Directory User represents an active Enterprise user.

Developers can receive Webhooks as employees are added, updated or removed, allowing for provisioning and de-provisioning Users within an application.

The data stored for employees vary per Directory provider and may include attributes such as photo URLs, pay groups, supervisors, etc. Where available, the WorkOS API will provide the additional data in the raw_attributes field when fetching Directory User records.

Example Directory User

 {
  "id": "directory_user_01E1JG7J09H96KYP8HM9B0G5SJ",
  "idp_id": "2836",
  "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
  "organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y",
  "first_name": "Marcelina",
  "last_name": "Davis",
  "emails": [
    {
      "primary": true,
      "type": "work",
      "value": "[email protected]foo-corp.com"
    }
  ],
  "username": "[email protected]foo-corp.com",
  "groups": [
    {
      "id": "directory_group_01E64QTDNS0EGJ0FMCVY9BWGZT",
      "name": "Engineering",
      "created_at": "2021-06-25T19:07:33.155Z",
      "updated_at": "2021-06-25T19:07:33.155Z",
      "raw_attributes": {}
    }
  ],
  "state": "active",
  "created_at": "2021-06-25T19:07:33.155Z",
  "updated_at": "2021-06-25T19:07:33.155Z",
  "custom_attributes": {
    "department": "Engineering"
  },
  "raw_attributes": {}
}

`directory_user`

Unique identifier for the Directory User.

Unique identifier for the user, assigned by the Directory Provider. Different Directory Providers use different ID formats.

One possible use case for idp_id is associating the Directory User with their SSO Profile.

The identifier of the Directory the Directory User belongs to.

The identifier for the Organization in which the Directory resides.

The first name of the user.

The last name of the user.

The emails of the user.

The username of the user.

The groups that the user is a member of.

The state of the user.

active

suspended

inactive

An object containing the custom attribute mapping for the Directory Provider.

An object containing the data returned from the Directory Provider.

The timestamp when the Directory User was created.

The timestamp when the Directory User was last updated.

Get a Directory User

Section titled Get a Directory User

Get the details of an existing Directory User.

Request

 curl https://api.workos.com/directory_users/directory_user_01E1JG7J09H96KYP8HM9B0G5SJ \
  --header "Authorization: Bearer sk_example_123456789"

 {
  "id": "directory_user_01E1JG7J09H96KYP8HM9B0G5SJ",
  "idp_id": "2836",
  "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
  "organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y",
  "first_name": "Marcelina",
  "last_name": "Davis",
  "emails": [
    {
      "primary": true,
      "type": "work",
      "value": "[email protected]foo-corp.com"
    }
  ],
  "username": "[email protected]foo-corp.com",
  "groups": [
    {
      "id": "directory_group_01E64QTDNS0EGJ0FMCVY9BWGZT",
      "name": "Engineering",
      "created_at": "2021-06-25T19:07:33.155Z",
      "updated_at": "2021-06-25T19:07:33.155Z",
      "raw_attributes": {}
    }
  ],
  "state": "active",
  "created_at": "2021-06-25T19:07:33.155Z",
  "updated_at": "2021-06-25T19:07:33.155Z",
  "custom_attributes": {
    "department": "Engineering"
  },
  "raw_attributes": {}
}

`GET/directory_users/:id`

`Parameters`

Unique identifier for the Directory User.

`Returns`

directory_user

List Directory Users

Section titled List Directory Users

Get a list of all of existing Directory Users matching the criteria specified.

Request

 curl https://api.workos.com/directory_users?directory=directory_01ECAZ4NV9QMV47GW873HDCX74 \
  --header "Authorization: Bearer sk_example_123456789"

 {
  "data": [
    {
      "id": "directory_user_01E1JJHG3BFJ3FNRRHSFWEBNCS",
      "idp_id": "1902",
      "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
      "organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y",
      "emails": [
        {
          "primary": true,
          "type": "work",
          "value": "[email protected]foo-corp.com"
        }
      ],
      "first_name": "Jan",
      "last_name": "Brown",
      "username": "[email protected]foo-corp.com",
      "groups": [
        {
          "id": "directory_group_01E64QTDNS0EGJ0FMCVY9BWGZT",
          "name": "Engineering",
          "created_at": "2021-06-25T19:07:33.155Z",
          "updated_at": "2021-06-25T19:07:33.155Z"
        }
      ],
      "state": "active",
      "created_at": "2021-06-25T19:07:33.155Z",
      "updated_at": "2021-06-25T19:07:33.155Z",
      "custom_attributes": {
        "department": "Engineering"
      }
    },
    {
      "id": "directory_user_01E1JJHG10ANRA2V6PAX3GD7TE",
      "idp_id": "8953",
      "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
      "organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y",
      "emails": [
        {
          "primary": true,
          "type": "work",
          "value": "[email protected]foo-corp.com"
        }
      ],
      "first_name": "Rosalinda",
      "last_name": "Swift",
      "username": "[email protected]foo-corp.com",
      "groups": [
        {
          "id": "directory_group_01E64QTDNS0EGJ0FMCVY9BWGZT",
          "name": "Engineering",
          "created_at": "2021-06-25T19:07:33.155Z",
          "updated_at": "2021-06-25T19:07:33.155Z"
        }
      ],
      "state": "active",
      "created_at": "2021-06-25T19:07:33.155Z",
      "updated_at": "2021-06-25T19:07:33.155Z",
      "custom_attributes": {
        "department": "Engineering"
      }
    }
  ],
  "object": "list",
  "list_metadata": {
    "after": "directory_user_01E4RH82CC8QAP8JTRCTNDSS4C",
    "before": "directory_user_01E4RH828021B9ZZB8KH8E2Z1W"
  }
}

`GET/directory_user`

`Parameters`

Unique identifier of the WorkOS Directory.

This value can be obtained from the WorkOS dashboard or from the WorkOS API.

Unique identifier of the WorkOS Directory Group.

This value can be obtained from the WorkOS API.

Upper limit on the number of objects to return, between 1 and 100. The default value is 10.

Order the results by the created_at timestamp. Supported values are "asc" and "desc" for ascending and descending order respectively.

`Returns`

object

Array of Directory Users in descending order by created_at timestamp.

Since these can be bulk processed (ex. 10 updates were batched process), there is a secondary sort on the identifier, i.e. id.

Directory User Webhooks

Section titled Directory User Webhooks

Triggers when a user has been created, updated, or deleted.

Created

 {
  "event": "dsync.user.created",
  "id": "wh_07FKJ843CVE8F7BXQSPFH0M53V",
  "data": {
    "id": "directory_user_01E1X1B89NH8Z3SDFJR4H7RGX7",
    "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
    "organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y",
    "idp_id": "8931",
    "emails": [
      {
        "primary": true,
        "type": "work",
        "value": "[email protected]foo-corp.com"
      }
    ],
    "first_name": "Lela",
    "last_name": "Block",
    "username": "[email protected]foo-corp.com",
    "state": "active",
    "created_at": "2021-06-25T19:07:33.155Z",
    "updated_at": "2021-06-25T19:07:33.155Z",
    "custom_attributes": {
      "department": "Engineering"
    },
    "raw_attributes": {}
  }
}

 {
  "event": "dsync.user.updated",
  "id": "wh_08FKJ843CVE8F7BXQSPFH0M53V",
  "data": {
    "id": "directory_user_01E1X1B89NH8Z3SDFJR4H7RGX7",
    "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
    "organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y",
    "idp_id": "8931",
    "emails": [
      {
        "primary": true,
        "type": "work",
        "value": "[email protected]foo-corp.com"
      }
    ],
    "first_name": "Veda",
    "last_name": "Block",
    "username": "[email protected]foo-corp.com",
    "state": "active",
    "created_at": "2021-06-25T19:07:33.155Z",
    "updated_at": "2021-06-25T19:07:33.155Z",
    "custom_attributes": {
      "department": "Engineering"
    },
    "raw_attributes": {},
    "previous_attributes": {}
  }
}

 {
  "event": "dsync.user.deleted",
  "id": "wh_09FKJ843CVE8F7BXQSPFH0M53V",
  "data": {
    "id": "directory_user_01E1X1B89NH8Z3SDFJR4H7RGX7",
    "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
    "organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y",
    "idp_id": "8931",
    "emails": [
      {
        "primary": true,
        "type": "work",
        "value": "[email protected]foo-corp.com"
      }
    ],
    "first_name": "Lela",
    "last_name": "Block",
    "username": "[email protected]foo-corp.com",
    "state": "inactive",
    "created_at": "2021-06-25T19:07:33.155Z",
    "updated_at": "2021-06-25T19:07:33.155Z",
    "custom_attributes": {
      "department": "Engineering"
    },
    "raw_attributes": {}
  }
}

`dsync.user.created dsync.user.updated dsync.user.deleted`

The type of webhook event.

Unique identifier for the webhook.

The updated Directory User.

Previous Attributes

The payload for dsync.user.updated webhooks shows changes between Directory Group snapshots in a previous_attributes property.

The changes in the object are shallow differences for root properties, raw_attributes, and custom_attributes. If the current snapshot has a new attribute that did not exist previously, then the value for the attribute will be indicated as null.

Directory Group

Section titled Directory Group

A Directory Group represents an Enterprise organizational unit of users.

Developers can receive Webhooks as groups are added, updated, or removed, allowing for group-based resource access.

At this time, only the Group identifier and name attributes are returned.

Example Directory Group

 {
  "id": "directory_group_01E1JJS84MFPPQ3G655FHTKX6Z",
  "idp_id": "02grqrue4294w24",
  "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
  "organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y",
  "name": "Developers",
  "created_at": "2021-06-25T19:07:33.155Z",
  "updated_at": "2021-06-25T19:07:33.155Z",
  "raw_attributes": {}
}

`directory_group`

Unique identifier for the Directory Group.

Unique identifier for the group, assigned by the Directory Provider. Different Directory Providers use different ID formats.

The identifier of the Directory the Directory Group belongs to.

The identifier for the Organization in which the Directory resides.

The name of the Directory Group.

The timestamp when the Directory Group was created.

The timestamp when the Directory Group was last updated.

An object containing the data returned from the Directory Provider.

Get a Directory Group

Section titled Get a Directory Group

Get the details of an existing Directory Group.

Request

 curl https://api.workos.com/directory_groups/directory_group_01E1JJS84MFPPQ3G655FHTKX6Z \
  --header "Authorization: Bearer sk_example_123456789"

 {
  "id": "directory_group_01E1JJS84MFPPQ3G655FHTKX6Z",
  "idp_id": "02grqrue4294w24",
  "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
  "organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y",
  "name": "Developers",
  "created_at": "2021-06-25T19:07:33.155Z",
  "updated_at": "2021-06-25T19:07:33.155Z",
  "raw_attributes": {}
}

`GET/directory_groups/:id`

`Parameters`

Unique identifier for the Directory Group.

`Returns`

directory_group

List Directory Groups

Section titled List Directory Groups

Get a list of all of existing directory groups matching the criteria specified.

Request

 curl https://api.workos.com/directory_groups?directory=directory_01ECAZ4NV9QMV47GW873HDCX74 \
  --header "Authorization: Bearer sk_example_123456789"

 {
  "data": [
    {
      "id": "directory_group_01E1JJS84MFPPQ3G655FHTKX6Z",
      "idp_id": "02grqrue4294w24",
      "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
      "organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y",
      "name": "Developers",
      "created_at": "2021-06-25T19:07:33.155Z",
      "updated_at": "2021-06-25T19:07:33.155Z",
      "raw_attributes": {}
    }
  ],
  "list_metadata": {
    "after": "directory_group_01E1JJS84MFPPQ3G655FHTKX6Z",
    "before": "directory_group_01E1JJS84MFPPQ3G655FHTKX6Z"
  }
}

`GET/directory_groups`

`Parameters`

Unique identifier of the WorkOS Directory.

This value can be obtained from the WorkOS dashboard or from the WorkOS API.

Unique identifier of the WorkOS Directory User.

This value can be obtained from the WorkOS API.

Upper limit on the number of objects to return, between 1 and 100. The default value is 10.

Order the results by the created_at timestamp. Supported values are "asc" and "desc" for ascending and descending order respectively.

`Returns`

object

Array of Directory Groups in descending order by created_at timestamp.

Directory Group Webhooks

Section titled Directory Group Webhooks

Triggers when a group has been created, updated, or deleted. It also triggers when a user is added or removed from a group.

Created

 {
  "event": "dsync.group.created",
  "id": "wh_44FKJ843CVE8F7BXQSPFH0M53V",
  "data": {
    "id": "directory_group_01E1X5GPMMXF4T1DCERMVEEPVW",
    "idp_id": "02grqrue4294w24",
    "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
    "organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y",
    "name": "Developers",
    "created_at": "2021-06-25T19:07:33.155Z",
    "updated_at": "2021-06-25T19:07:33.155Z",
    "raw_attributes": {}
  }
}

 {
  "event": "dsync.group.updated",
  "id": "wh_54FKJ843CVE8F7BXQSPFH0M53V",
  "data": {
    "id": "directory_group_01E1X5GPMMXF4T1DCERMVEEPVW",
    "idp_id": "02grqrue4294w24",
    "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
    "organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y",
    "name": "Developers",
    "created_at": "2021-06-25T19:07:33.155Z",
    "updated_at": "2021-06-25T19:07:33.155Z",
    "raw_attributes": {},
    "previous_attributes": {}
  }
}

 {
  "event": "dsync.group.deleted",
  "id": "wh_06FKJ843CVE8F7BXQSPFH0M53V",
  "data": {
    "id": "directory_group_01E1X5GPMMXF4T1DCERMVEEPVW",
    "idp_id": "02grqrue4294w24",
    "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
    "organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y",
    "name": "Developers",
    "created_at": "2021-06-25T19:07:33.155Z",
    "updated_at": "2021-06-25T19:07:33.155Z",
    "raw_attributes": {}
  }
}

 {
  "event": "dsync.group.user_added",
  "id": "wh_04FKJ843CVE8F7BXQSPFH0M53V",
  "data": {
    "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
    "user": {
      "id": "directory_user_01E1X56GH84T3FB41SD6PZGDBX",
      "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
      "organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y",
      "idp_id": "2936",
      "emails": [
        {
          "primary": true,
          "type": "work",
          "value": "[email protected]foo-corp.com"
        }
      ],
      "first_name": "Eric",
      "last_name": "Schneider",
      "username": "[email protected]foo-corp.com",
      "state": "active",
      "created_at": "2021-06-25T19:07:33.155Z",
      "updated_at": "2021-06-25T19:07:33.155Z",
      "custom_attributes": {
        "department": "Engineering"
      },
      "raw_attributes": {}
    },
    "group": {
      "id": "directory_group_01E1X5GPMMXF4T1DCERMVEEPVW",
      "name": "Developers"
    }
  }
}

 {
  "event": "dsync.group.user_removed",
  "id": "wh_05FKJ843CVE8F7BXQSPFH0M53V",
  "data": {
    "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
    "user": {
      "id": "directory_user_01E1X56GH84T3FB41SD6PZGDBX",
      "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
      "organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y",
      "idp_id": "2936",
      "emails": [
        {
          "primary": true,
          "type": "work",
          "value": "[email protected]foo-corp.com"
        }
      ],
      "first_name": "Eric",
      "last_name": "Schneider",
      "username": "[email protected]foo-corp.com",
      "state": "active",
      "created_at": "2021-06-25T19:07:33.155Z",
      "updated_at": "2021-06-25T19:07:33.155Z",
      "custom_attributes": {
        "department": "Engineering"
      },
      "raw_attributes": {}
    },
    "group": {
      "id": "directory_group_01E1X5GPMMXF4T1DCERMVEEPVW",
      "name": "Developers"
    }
  }
}

`dsync.group.created dsync.group.updated dsync.group.deleted dsync.group.user_added dsync.group.user_removed`

The type of webhook event.

Unique identifier for the webhook.

The updated Directory Group or Directory User.

Previous Attributes

The payload for dsync.group.updated webhooks shows changes between Directory Group snapshots in a previous_attributes property.

Admin Portal

Section titled Admin Portal

The Admin Portal is a standalone application where your users can configure and manage WorkOS resources such as Connections and Directories that are scoped to their Organization.

Portal Link

Section titled Portal Link

A Portal Link is a temporary endpoint to initiate an Admin Portal session. It expires five minutes after issuance.

Example Portal Link URL

 https://id.workos.com/portal/launch?secret=JteZqfJZqUcgWGaYCC6iI0gW0

Generate a Portal Link

Section titled Generate a Portal Link

Generate a Portal Link scoped to an Organization.

Request

 curl --request POST \
  --url https://api.workos.com/portal/generate_link \
  --header "Authorization: Bearer sk_example_123456789" \
  -d organization="org_01EHZNVPK3SFK441A1RGBFSHRT" \
  -d intent="sso"

 {
  "link": "https://id.workos.com/portal/launch?secret=JteZqfJZqUcgWGaYCC6iI0gW0"
}

`POST/portal/generate_link`

`Parameters`

An Organization identifier.

The intent of the Admin Portal.

sso - Launch Admin Portal for creating SSO connections
dsync - Launch Admin Portal for creating directory sync connections
audit_logs - Launch Admin Portal for viewing Audit Logs

The URL to which WorkOS should send users when they click on the link to return to your website.

`Returns`

object

An ephemeral link to initiate the Admin Portal.

Magic Link

Section titled Magic Link

The Magic Link API can be used to add Passwordless Authentication to your app.

Passwordless Session

Section titled Passwordless Session

An object representing a passwordless authentication session.

Example Passwordless Session

 {
  "object": "passwordless_session",
  "id": "passwordless_session_01EHDAK2BFGWCSZXP9HGZ3VK8C",
  "email": "[email protected]foo-corp.com",
  "expires_at": "2020-08-13T05:50:00.000Z",
  "link": "https://auth.workos.com/passwordless/4TeRexuejWCKs9rrFOIuLRYEr/confirm"
}

`passwordless_session`

Distinguishes the Paswordless Session object.

The unique ID of the session.

The email address of the user for the session.

The ISO-8601 datetime at which the session expires.

The link for the user to authenticate with. You can use this link to send a custom email to the user, or send an email using Email a Magic Link to the user.

Once a user has authenticated with the link, WorkOS issues a redirect to the Environment’s default redirect URI, with a code parameter and, if provided during session creation, a state parameter.

Code can then be exchanged for an access token and user Profile. To perform this exchange, the Developer should make a POST request to the /sso/token endpoint.

If the link has expired, WorkOS will issue a redirect with an error query parameter and value of access_denied.

Create Passwordless Session

Section titled Create Passwordless Session

Create a Passwordless Session for a Magic Link Connection.

Request

 curl --request POST \
  --url https://api.workos.com/passwordless/sessions \
  --header "Authorization: Bearer sk_example_123456789" \
  -d email="[email protected]foo-corp.com" \
  -d type="MagicLink"

 {
  "object": "passwordless_session",
  "id": "passwordless_session_01EHDAK2BFGWCSZXP9HGZ3VK8C",
  "email": "[email protected]foo-corp.com",
  "expires_at": "2020-08-13T05:50:00.000Z",
  "link": "https://auth.workos.com/passwordless/4TeRexuejWCKs9rrFOIuLRYEr/confirm"
}

`POST/passwordless/sessions`

`Parameters`

The email of the user to authenticate.

The type of Passwordless Session to create. Currently, the only supported value is MagicLink.

Optional parameter that a developer can choose to include in their authorization URL. If included, it will override the default Redirect URI set in the dashboard. This is the location your user will be redirected to once the session has been completed successfully.

The number of seconds the Passwordless Session should live before expiring.

This value must be between 300 (5 minutes) and 86400 (24 hours), inclusive.

Optional parameter that a developer can choose to include in their authorization URL. If included, then the redirect URI received from WorkOS will contain the exact state that was passed in the authorization URL.

The state parameter can be used to encode arbitrary information to help restore application state between redirects.

`Returns`

passwordless_session

Email a Magic Link

Section titled Email a Magic Link

Email a user the Magic Link confirmation URL.

Request

 curl --request POST \
  --url https://api.workos.com/passwordless/sessions/passwordless_session_01EG1BHJMVYMFBQYZTTC0N73CR/send \
  --header "Authorization: Bearer sk_example_123456789"

 {
  "success": true
}

`POST/passwordless/sessions/:id/send`

`Parameters`

The unique identifier of the Passwordless Session to send an email for.

`Returns`

object

A confirmation that the Magic Link was sent.

Audit Logs

Section titled Audit Logs

Audit Logs are a collection of events that contain information relevant to notable actions taken by users in your application. Every event in the collection contains details regarding what kind of action was taken (action), who performed the action (actor), what resources were affected by the action (targets), and additional details of when and where the action took place.

Create Event

Section titled Create Event

Create an Audit Log Event.

Request

 curl --request POST \
  --url https://api.workos.com/audit_logs/events \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: 884793cd-bef4-46cf-8790-e3d4957a09ce" \
  -d @- <<BODY
  {
    "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
    "event": {
      "action": "user.signed_in",
      "occurred_at": "2022-09-02T16:35:39.317Z",
      "version": 1,
      "actor": {
        "type": "user",
        "id": "user_id",
        "name": "Jon Smith",
        "metadata": {
          "role": "admin"
        }
      },
      "targets": [
        {
          "type": "user",
          "id": "user_id",
          "name": "Jon Smith"
        },
        {
          "type": "team",
          "id": "team_id",
          "metadata": {
            "extra": "data"
          }
        }
      ],
      "context": {
        "location": "1.1.1.1",
        "user_agent": "Chrome/104.0.0.0"
      },
      "metadata": {
        "extra": "data"
      }
    }
  }
BODY

`POST/audit_logs/events`

`Parameters`

The unique ID of the Organization.

Identifier of what happened

ISO 8601 value of when the action occurred

What schema version the event is associated with

Actor type

Actor identifier

Optional actor name

Additional data that should be associated with the event or entity. There is a limit of 50 keys. Key names can be up to 40 characters long, and values can be up to 500 characters long.

Target type

Target identifier

Optional target name

Additional data that should be associated with the event or entity. There is a limit of 50 keys. Key names can be up to 40 characters long, and values can be up to 500 characters long.

IP Address or some other geolocation identifier

User agent string

Additional data that should be associated with the event or entity. There is a limit of 50 keys. Key names can be up to 40 characters long, and values can be up to 500 characters long.

Audit Log Export

Section titled Audit Log Export

An object representing an Audit Log Export.

Audit Log Export

 {
  "object": "audit_log_export",
  "id": "audit_log_export_01GBZK5MP7TD1YCFQHFR22180V",
  "state": "ready",
  "url": "https://exports.audit-logs.com/audit-log-exports/export.csv",
  "created_at": "2022-09-02T17:14:57.094Z",
  "updated_at": "2022-09-02T17:14:57.094Z"
}

`audit_log_export`

Distinguishes the Audit Log Export object.

The unique ID of the Audit Log Export.

The timestamp when the Audit Log Export was created.

The timestamp when the Audit Log Export was last updated.

The state of the export. Can be pending, ready, or error.

A URL to the CSV file. Only defined when state is ready.

Create Export

Section titled Create Export

Create an Audit Log Export.

Request

 curl --request POST \
  --url https://api.workos.com/audit_logs/exports \
  --header "Authorization: Bearer sk_example_123456789" \
  -d organization_id="org_01EHZNVPK3SFK441A1RGBFSHRT" \
  -d range_start="2022-07-02T18:09:06.996Z" \
  -d range_end="2022-09-02T18:09:06.996Z" \
  -d 'actions[]=user.signed_in' \
  -d 'actors[]=Jon Smith' \
  -d 'targets[]=team'

`POST/audit_logs/exports`

`Parameters`

The unique ID of the Organization.

ISO 8601 value for start of the export range.

ISO 8601 value for end of the export range.

List of actions to filter against.

List of actor names to filter against.

List of target types to filter against.

`Returns`

audit_log_export

Get Export

Section titled Get Export

Get an Audit Log Export.

Request

 curl https://api.workos.com/audit_logs/exports/audit_log_export_01GBZK5MP7TD1YCFQHFR22180V \
  --header "Authorization: Bearer sk_example_123456789"

`GET/audit_logs/exports/:id`

`Parameters`

The unique ID of the Audit Log Export.

`Returns`

audit_log_export

The URL will expire after 10 minutes. If the export is needed again at a later time, refetching the export will regenerate the URL.

Multi-Factor Authentication

Section titled Multi-Factor Authentication

The multi-factor authentication (MFA) API can be used to add additional factors of authentication to existing authentication strategies.

The API currently supports both time-based one-time passwords (TOTP) and SMS factors.

Authentication Factor

Section titled Authentication Factor

An object representing an Authentication Factor.

Example Authentication Factor

 {
  "object": "authentication_factor",
  "id": "auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ",
  "created_at": "2022-02-15T15:14:19.392Z",
  "updated_at": "2022-02-15T15:14:19.392Z",
  "type": "totp",
  "totp": {
    "qr_code": "data:image/png;base64,{base64EncodedPng}",
    "secret": "NAGCCFS3EYRB422HNAKAKY3XDUORMSRF",
    "uri": "otpauth://totp/FooCorp:[email protected]foo-corp.com?secret=NAGCCFS3EYRB422HNAKAKY3XDUORMSRF&issuer=FooCorp"
  }
}

`authentication_factor`

Distinguishes the Authentication Factor object.

The unique ID of the Factor.

The timestamp when the Factor was created.

The timestamp when the Factor was last updated.

The type the Factor. Can be either totp or sms.

Base64 encoded image containing scannable QR code.

TOTP secret that can be manually entered into some authenticator apps in place of scanning QR code.

The otpauth URI that is encoded the provided qr_code.

Phone number that the Factor was enrolled with.

Authentication Challenge

Section titled Authentication Challenge

An object representing a Challenge of an Authentication Factor.

Example Authentication Challenge

 {
  "object": "authentication_challenge",
  "id": "auth_challenge_01FVYZWQTZQ5VB6BC5MPG2EYC5",
  "created_at": "2022-02-15T15:26:53.274Z",
  "updated_at": "2022-02-15T15:26:53.274Z",
  "expires_at": "2022-02-15T15:36:53.279Z",
  "authentication_factor_id": "auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ"
}

`authentication_challenge`

Distinguishes the Authentication Challenge object.

The unique ID of the Authentication Challenge.

The timestamp when the Challenge was created.

The timestamp when the Challenge was last updated.

The timestamp when the Challenge will expire. Does not apply to totp factors.

The unique ID of the Authentication Factor the Challenge belongs to.

Enroll Factor

Section titled Enroll Factor

Enrolls an Authentication Factor to be used as an additional factor of authentication. The returned ID should can later be used to create an authentication Challenge.

Request

 curl --request POST \
  --url https://api.workos.com/auth/factors/enroll \
  --header "Authorization: Bearer sk_example_123456789" \
  -d type="totp" \
  -d totp_issuer="Foo Corp" \
  -d totp_user="[email protected]foo-corp.com"

 {
  "object": "authentication_factor",
  "id": "auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ",
  "created_at": "2022-02-15T15:14:19.392Z",
  "updated_at": "2022-02-15T15:14:19.392Z",
  "type": "totp",
  "totp": {
    "qr_code": "data:image/png;base64,{base64EncodedPng}",
    "secret": "NAGCCFS3EYRB422HNAKAKY3XDUORMSRF",
    "uri": "otpauth://totp/FooCorp:[email protected]foo-corp.com?secret=NAGCCFS3EYRB422HNAKAKY3XDUORMSRF&issuer=FooCorp"
  }
}

`POST/auth/factors/enroll`

`Parameters`

The type of factor you wish to enroll.

totp

sms

An identifier for the organization issuing the challenge. Should be the name of your application or company. Required when type is totp.

An identifier for the user. Used by authenticator apps to label connections. Required when type is totp.

A valid phone number for an SMS enabled device. Required when type is sms.

`Returns`

authentication_factor

Challenge Factor

Section titled Challenge Factor

Creates a Challenge for an Authentication Factor.

Request

 curl --request POST \
  --url https://api.workos.com/auth/factors/auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ/challenge \
  --header "Authorization: Bearer sk_example_123456789" \
  -d authentication_factor_id="auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ"

 {
  "object": "authentication_challenge",
  "id": "auth_challenge_01FVYZWQTZQ5VB6BC5MPG2EYC5",
  "created_at": "2022-02-15T15:26:53.274Z",
  "updated_at": "2022-02-15T15:26:53.274Z",
  "expires_at": "2022-02-15T15:36:53.279Z",
  "authentication_factor_id": "auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ"
}

`POST/auth/factors/:id/challenge`

`Parameters`

The unique ID of the Authentication Factor to be challenged.

Optional template for SMS messages. Only applicable for sms Factors. Use the {{code}} token to inject the one-time code into the message. E.g., Your Foo Corp one-time code is {{code}}.

`Returns`

authentication_challenge

Verify Challenge

Section titled Verify Challenge

Verify Authentication Challenge.

Request

 curl --request POST \
  --url https://api.workos.com/auth/challenges/auth_challenge_01FVYZWQTZQ5VB6BC5MPG2EYC5/verify \
  --header "Authorization: Bearer sk_example_123456789" \
  -d code="123456"

 {
  "challenge": {
    "object": "authentication_challenge",
    "id": "auth_challenge_01FVYZWQTZQ5VB6BC5MPG2EYC5",
    "created_at": "2022-02-15T15:26:53.274Z",
    "updated_at": "2022-02-15T15:26:53.274Z",
    "expires_at": "2022-02-15T15:36:53.279Z",
    "authentication_factor_id": "auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ"
  },
  "valid": true
}

`POST/auth/challenges/:id/verify`

`Parameters`

The unique ID of the authentication Challenge.

The 6 digit code to be verified.

`Returns`

object

The relevant Authentication Challenge.

Indicates whether the code was correct.

API Reference

Client Libraries

API Keys

Secure your API Keys

In Staging

In Production

Errors

Pagination

Webhooks

Idempotency

Organization

organization

object"organization"

idstring

namestring

allow_profiles_outside_organizationboolean

created_atstring

updated_atstring

domainsarray

Get an Organization

GET/organizations/:id

Parameters

idstring

Returns

List Organizations

GET/organizations

Parameters

domains?string[]

limit?number

before?string

after?string

order?"asc" | "desc"

Returns

dataarray

list_metadataobject

beforestring

afterstring

Create an Organization

POST/organizations

Parameters

namestring

allow_profiles_outside_organization?boolean

domains?array of strings

Returns

Update an Organization

PUT/organizations/:id

Parameters

namestring

allow_profiles_outside_organization?boolean

domains?array of strings

Returns

Delete an Organization

DELETE/organizations/:id

Parameters

idstring

Organization Domain

organization_domain

object"organization_domain"

idstring

domainstring

Single Sign-On

Redirect URI

Get Authorization URL

GET/sso/authorize

response_type"code"

client_idstring

connection?string

organization?string

provider?string

state?string

login_hint?string

domain_hint?string

Returns

urlstring

Error codes

Profile

profile

object"profile"

idstring

connection_idstring

`organization`

`GET/organizations/:id`

`Parameters`

`Returns`

`GET/organizations`

`Parameters`

`Returns`

`POST/organizations`

`Parameters`

`Returns`

`PUT/organizations/:id`

`Parameters`

`Returns`

`DELETE/organizations/:id`

`Parameters`

`organization_domain`

`GET/sso/authorize`

`Returns`

`profile`

`POST/sso/token`

`Parameters`

`Returns`

`GET/sso/profile`

`Parameters`

`Returns`

`connection`

`GET/connections/:id`

`Parameters`

`Returns`

`GET/connections`

`Parameters`

`Returns`

`DELETE/connections/:id`

`Parameters`

`connection.activated connection.deactivated connection.deleted`

`directory`