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.

Sign in to see code examples customized with your API keys and data.

https://api.workos.com

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

You can test the API directly with cURL, or use the Postman collection for convenience.

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.

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.

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.

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 creation time.

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

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.

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.

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.

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.

{
  "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"
    }
  ]
}

Get the details of an existing organization.

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

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

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

Creates a new organization in the current environment.

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

Updates an organization in the current environment.

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"'

Deletes an organization in the current environment.

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

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.

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

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.

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.

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

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.

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

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.

OAuth Provider Errors

In addition to the other error codes, OAuth providers may also return the following error codes.

access_denied

The user denied an OAuth authorization request at the Identity Provider.

oauth_failed

An OAuth authorization request failed for a user.

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.

{
  "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 an access token along with the user Profile using the code passed to your Redirect URI.

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'

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.

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

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.

{
  "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 the details of an existing connection.

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

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

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

Delete an existing connection.

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

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

{
  "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"
      }
    ]
  }
}

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.

A Directory stores information about an Enterprise Client’s employee management system.

Synchronizing with a Directory enables Developers to receive changes to an Enterprise Client’s User and Group structure.

Directory Providers vary in implementation details and may require different sets of fields for integration, such as API keys, subdomains, endpoints, usernames, etc. Where available, the WorkOS API will provide these fields when fetching Directory records.

{
  "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 the details of an existing directory.

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

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

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

Delete an existing directory.

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

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

{
  "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"
      }
    ]
  }
}

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.

{
  "id": "directory_user_01E1JG7J09H96KYP8HM9B0G5SJ",
  "idp_id": "2836",
  "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
  "organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y",
  "first_name": "Marcelina",
  "last_name": "Davis",
  "job_title": "Software Engineer",
  "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 the details of an existing Directory User.

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

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

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

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

{
  "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",
    "job_title": "Software Engineer",
    "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

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.

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.

{
  "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 the details of an existing Directory Group.

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

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

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

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

{
  "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": {}
  }
}

Previous Attributes

The payload for dsync.group.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.

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.

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

https://setup.workos.com?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Generate a Portal Link scoped to an Organization.

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

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

An object representing a passwordless authentication 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"
}

Create a Passwordless Session for a Magic Link Connection.

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"

Email a user the Magic Link confirmation URL.

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

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.

Emits an Audit Log Event.

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_TF4C5938",
        "metadata": {
          "role": "admin",
        },
      },
      "targets": [
        {
          "type": 'user',
          "id": 'user_98432YHF',
          "name": 'Jon Smith',
        },
        {
          "type": "team",
          "id": "team_J8YASKA2",
          "metadata": {
            "owner": "user_01GBTCQ2",
          },
        },
      ],
      "context": {
        "location": "123.123.123.123",
        "user_agent": "Chrome/104.0.0.0",
      },
      "metadata": {
        "extra": "data",
      }
    }
  }
BODY

An object representing an 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"
}

Create an Audit Log Export.

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'