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.

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

API Base URL

Copy
https://api.workos.com

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.

  • Node.js

    Node.js

  • Ruby

    Ruby

  • Go

    Go

  • Python

    Python

  • PHP

    PHP

  • Laravel

    Laravel

  • .NET

    .NET

  • Java

    Java

Command Line

Copy
npm install @workos-inc/node

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 - requests over plain HTTP will fail.

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

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

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.

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.

All API requests must be made over HTTPS. Any requests made over plain HTTP will fail.

API Key

Switch
Copy
1
{secretKey}

Set API Key

Switch
Copy
1
2
3
import WorkOS from '@workos-inc/node';

const workos = new WorkOS('{secretKey}');

Errors

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

  • 2xx - Indicates success.
  • 4xx - Indicates an error, normally due to error caused by incorrect or missing request information (e.g. providing an incorrect API key).
  • 5xx - Indicates a WorkOS server error.

Status Codes

200

Successful request.

400

The request was not acceptable, often indicates the parameters were not 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.

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.

Attributes

  • id

    string

    Unique identifier for the Organization.

  • name

    string

    The name of the Organization.

  • allow_profiles_outside_organization

    boolean

    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.

    See here for more details.

  • created_at

    string

    The timestamp when the Organization was created.

  • updated_at

    string

    The timestamp when the Organization was last updated.

  • domains

    array of objects

    List of Organization Domains.

Endpoints

GET

/organizations

GET

/organizations/:id

POST

/organizations

PUT

/organizations/:id

DELETE

/organizations/:id

Organization Object

Copy
{
  "{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}": [
    {
      "id": "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A",
      "object": "organization_domain",
      "domain": "{foo-corp.com}"
    },
  ]
}

Get an Organization

Get the details of an existing organization.

Endpoint

GET

/organizations/:id

Path Parameters

Returns

An Organization.

Get an Organization

Switch
Copy
1
2
3
4
5
import WorkOS from '@workos-inc/node';

const workos = new WorkOS('{secretKey}');

const organization = await workos.organizations.getOrganization('org_01EHZNVPK3SFK441A1RGBFSHRT');

Response

Switch
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "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"
    }
  ]
}

List Organizations

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

Endpoint

GET

/organizations

Query Parameters

  • domains

    array of strings

    (optional)

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

  • after

    string

    (optional)

    A cursor to use for pagination. after is an Organization object ID that takes the form org_* and defines your place in the paginated list of Organization objects. after will return all Organizations created after the cursor's value.

  • before

    string

    (optional)

    A cursor to use for pagination. before is an Organization object ID that takes the form org_* and defines your place in the paginated list of Organization objects. before will return all Organizations created before the cursor's value.

  • limit

    integer

    (optional)

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

Returns

An object containing Organizations.

  • data

    array of objects

    Array of Organizations in descending order by created_at timestamp.

  • list_metadata

    object

    Contains cursor options to utilize for pagination.

List Organizations

Switch
Copy
1
2
3
4
5
6
7
import WorkOS from '@workos-inc/node';

const workos = new WorkOS('{secretKey}');

const organizations = await workos.organizations.listOrganizations({
  domains: ['{foo-corp.com}']
});

Response

Switch
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
{
  "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",
  }
}

Create an Organization

Create an Organization with a set of domains.

Endpoint

POST

/organizations

Body Parameters

  • name

    string

    The name of the Organization.

  • allow_profiles_outside_organization

    boolean

    (optional)

    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.

    See here for more details.

  • domains

    array of strings

    (optional)

    The domains of the Organization.

    At least one domain is required unless allow_profiles_outside_organization is true.

Returns

An Organization object.

Create an Organization

Switch
Copy
1
2
3
4
5
6
7
8
import WorkOS from '@workos-inc/node';

const workos = new WorkOS('{secretKey}');

const organization = await workos.organizations.createOrganization({
  name: 'Foo Corp',
  domains: ['{foo-corp.com}']
});

Response

Switch
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "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"
    }
  ]
}

Update an Organization

Update an Organization.

Endpoint

PUT

/organizations/:id

Body Parameters

  • name

    string

    The name of the Organization.

  • allow_profiles_outside_organization

    boolean

    (optional)

    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.

    See here for more details.

  • domains

    array of strings

    (optional)

    The domains of the Organization.

    At least one domain is required unless allow_profiles_outside_organization is true.

Returns

An Organization object.

Update an Organization

Switch
Copy
1
2
3
4
5
6
7
8
9
import WorkOS from '@workos-inc/node';

const workos = new WorkOS('{secretKey}');

const organization = await workos.organizations.updateOrganization({
  organization: 'org_01EHZNVPK3SFK441A1RGBFSHRT',
  name: 'Foo Corp',
  domains: ['{foo-corp.com}']
});

Response

Switch
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "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:08: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"
    }
  ]
}

Delete an Organization

Delete an existing organization.

Endpoint

DELETE

/organizations/:id

Path Parameters

Delete an Organization

Switch
Copy
1
2
3
4
5
import WorkOS from '@workos-inc/node';

const workos = new WorkOS('{secretKey}');

await workos.organizations.deleteOrganization('org_01EHZNVPK3SFK441A1RGBFSHRT')

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.

Attributes

  • id

    string

    Unique identifier for the Organization Domain.

  • domain

    string

    Domain for the Organization Domain.

Organization Domain Object

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

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.

Endpoints

GET

/sso/authorize

POST

/sso/token

GET

/connections/:id

GET

/connections

DELETE

/connections/:id

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.

Redirect URI

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

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.

Endpoint

GET

/sso/authorize

Query Parameters

  • client_id

    string

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

  • response_type

    string

    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.

  • redirect_uri

    string

    A Redirect URI to return an authorized user to.

  • connection

    string

    (optional)

    Value used to authenticate all users with the same connection.

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

  • domain

    string

    (optional)

    Value used to identify the correct connection and authentication strategy for an authenticating user.

    Provide the domain parameter when authenticating a user by their domain. For example, when a user enters their email address into a login form, the Developer would parse this email address for the domain and pass the domain as a domain parameter into their authorization URL. Then, WorkOS will use this domain value as a key to determine the connection and IdP to direct the user to for authentication.

  • provider

    string

    (optional)

    Value used to authenticate all users with the same connection and Identity 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.

  • state

    string

    (optional)

    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

The user is redirected to the generated OAuth 2.0 authorization URL to authenticate with their Identity Provider.

A code parameter is also provided and is a unique, short-lived (10 minutes) value that the Developer can exchange for an access token and user Profile. To perform this exchange, the Developer should make a POST request to the /sso/token endpoint.

If provided in the original request, the exact same state parameter and value is also returned.

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

The set of error values is provided below.

    Possible values

    • ambiguous_connection_selector

      A Connection could not be uniquely identified using the provided connection selector (e.g., domain). 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.

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

      See here for more details.

Get Authorization URL

Switch
Copy
1
2
3
4
5
6
7
8
9
10
import WorkOS from '@workos-inc/node';

const workos = new WorkOS('{secretKey}');

workos.sso.getAuthorizationURL({
  domain: '{foo-corp.com}',
  clientID: '{clientID}',
  redirectURI: 'https://your-app.com/callback',
  state: 'dj1kUXc0dzlXZ1hjUQ==',
});

Response

Switch
Copy
1
2
3
4
5
6
https://api.workos.com/sso/authorize?
  response_type=code&
  client_id={clientID}&
  redirect_uri=https://your-app.com/callback&
  domain={foo-corp.com}&
  state=dj1kUXc0dzlXZ1hjUQ==

Redirect URI

Switch
Copy
1
2
3
https://your-app.com/callback?
  code=01E2RJ4C05B52KKZ8FSRDAP23J&
  state=dj1kUXc0dzlXZ1hjUQ==

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.

Attributes

  • id

    string

    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.

  • object

    string

    String representing the object's type. Currently the only possible value is profile.

  • connection_type

    enum

    The type of SSO Connection used to authenticate the user.

      Possible values

      • ADFSSAML
      • Auth0SAML
      • AzureSAML
      • CyberArkSAML
      • DuoSAML
      • GenericOIDC
      • GenericSAML
      • GoogleOAuth
      • GoogleSAML
      • JumpCloudSAML
      • MicrosoftOAuth
      • OktaSAML
      • OneLoginSAML
      • PingFederateSAML
      • PingOneSAML
      • SalesforceSAML
      • VMwareSAML

  • email

    string

    The user's email address.

  • first_name

    string

    The user's first name.

  • last_name

    string

    The user's last name.

  • idp_id

    string

    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.

  • raw_attributes

    object

    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.

Profile Object

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

Get a Profile and Token

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

Endpoint

POST

/sso/token

Query Parameters

  • client_id

    string

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

  • client_secret

    string

    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.

  • grant_type

    string

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

  • code

    string

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

Returns

An object containing an access token and Profile.

  • access_token

    string

    An access token that can be used to manage sessions like one would a normal OAuth access token. Access tokens are one-time use and expire 10 minutes after they’re created. Session duration is up to the Developer.

  • profile

    object

    The user Profile.

Get a Profile

Switch
Copy
1
2
3
4
5
6
7
8
import WorkOS from '@workos-inc/node';

const workos = new WorkOS('{secretKey}');

await workos.sso.getProfileAndToken({
  code,
  clientID: '{clientID}',
});

Response

Switch
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "access_token": "01DMEK0J53CVMC32CK5SE0KZ8Q",
  "profile": {
    "id": "prof_01DMC79VCBZ0NY2099737PSVF1",
    "connection_id": "conn_01E4ZCR3C56J083X43JQXF3JK5",
    "connection_type": "okta",
    "email": "[email protected]{foo-corp.com}",
    "first_name": "Todd",
    "idp_id": "00u1a0ufowBJlzPlk357",
    "last_name": "Rundgren",
    "object": "profile",
    "raw_attributes": {{SSO raw_attributes}}
  }
}

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.

Attributes

  • object

    string

    String representing the object's type. Currently the only possible value is connection.

  • id

    string

    Unique identifier for the Connection.

  • organization_id

    string

    (optional)

    Unique identifier for the Organization in which the Connection resides.

  • connection_type

    enum

    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
      • Auth0SAML
      • AzureSAML
      • CyberArkSAML
      • DuoSAML
      • GenericOIDC
      • DuoSAML
      • GenericSAML
      • GoogleOAuth
      • GoogleSAML
      • JumpCloudSAML
      • MicrosoftOAuth
      • OktaSAML
      • OneLoginSAML
      • PingFederateSAML
      • PingOneSAML
      • SalesforceSAML
      • ShibbolethSAML
      • VMwareSAML

  • name

    string

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

  • state

    enum

    Indicates whether a Connection is able to authenticate users.

      Possible values

      • draft
      • active
      • inactive

  • created_at

    string

    The timestamp when the Connection was created.

  • updated_at

    string

    The timestamp when the Connection was last updated.

Connection Object

Copy
{
  "{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:07:33.155Z",
}

Get a Connection

Get the details of an existing connection.

Endpoint

GET

/connections/:id

Path Parameters

Returns

A Connection.

Get a Connection

Switch
Copy
1
2
3
4
5
import WorkOS from '@workos-inc/node';

const workos = new WorkOS('{secretKey}');

const connection = await workos.sso.getConnection('conn_01E4ZCR3C56J083X43JQXF3JK5');

Response

Switch
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "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:07:33.155Z",
  "domains": [
    {
      "id": "conn_domain_01EHWNFTAFCF3CQAE5A9Q0P1YB",
      "object": "connection_domain",
      "domain": "{foo-corp.com}"
    }
  ]
}

List Connections

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

Endpoint

GET

/connections

Query Parameters

  • after

    string

    (optional)

    A cursor to use for pagination. after is a Connection object ID that takes the form conn_* and defines your place in the paginated list of Connection objects. after will return all Connections created after the cursor's value.

  • before

    string

    (optional)

    A cursor to use for pagination. before is a Connection object ID that takes the form conn_* and defines your place in the paginated list of Connection objects. before will return all Connections created before the cursor's value.

  • connection_type

    enum

    (optional)

    Filter Connections by their type.

      Possible values

      • ADFSSAML
      • Auth0SAML
      • AzureSAML
      • CyberArkSAML
      • DuoSAML
      • GenericOIDC
      • GenericSAML
      • GoogleOAuth
      • GoogleSAML
      • JumpCloudSAML
      • MicrosoftOAuth
      • OktaSAML
      • OneLoginSAML
      • PingFederateSAML
      • PingOneSAML
      • SalesforceSAML
      • VMwareSAML

  • domain

    string

    (optional)

    Filter Connections by their associated domain.

  • organization_id

    string

    (optional)

    Filter Connections by their associated organization.

  • limit

    integer

    (optional)

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

Returns

An object containing Connections and metadata.

  • data

    array of objects

    An array of Connections in descending order by created_at timestamp.

  • list_metadata

    object

    Contains cursor options to utilize for pagination.

List Connections

Switch
Copy
1
2
3
4
5
import WorkOS from '@workos-inc/node';

const workos = new WorkOS('{secretKey}');

const connections = await workos.sso.listConnections();

Response

Switch
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
{
  "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": "conn_01EKKZXY1C4500PWY67PNQ3RGK",
  }
}

Delete a Connection

Delete an existing connection.

Endpoint

DELETE

/connections/:id

Path Parameters

Delete a Connection

Switch
Copy
1
2
3
4
5
import WorkOS from '@workos-inc/node';

const workos = new WorkOS('{secretKey}');

await workos.sso.deleteConnection('conn_01E2NPPCT7XQ2MVVYDHWGK1WN4')

Magic Link

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

Endpoints

POST

/passwordless/sessions

POST

/passwordless/sessions/:id/send

Passwordless Session

An object representing a passwordless authentication session.

Attributes

  • id

    string

    The unique ID of the session.

  • email

    string

    The email address of the user for the session.

  • expires_at

    date

    The ISO-8601 datetime at which the session expires.

  • link

    string

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

  • object

    string

    String representing the object's type. Currently, the only possible value is passwordless_session.

Passwordless Session Object

Copy
{
  "{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",
  "{object}": "passwordless_session"
}

Create Passwordless Session

Create a Passwordless Session for a Magic Link Connection.

Endpoint

POST

/passwordless/sessions

Body Parameters

  • email

    string

    The email of the user to authenticate.

  • type

    string

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

  • connection

    string

    (optional)

    Value containing the ID of a specific Connection.

    This can be used to create a Passwordless Session for a specific Connection rather than relying on the domain from the email to determine the Organization and Connection.

  • redirect_uri

    string

    (optional)

    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.

  • expires_in

    number

    (optional)

    , default is 300

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

    This value must be between 300 (5 minutes) and 1800 (30 minutes), inclusive.

  • state

    string

    (optional)

    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

A Passwordless Session.

Create a Passwordless Session

Switch
Copy
1
2
3
4
5
6
7
8
import WorkOS from '@workos-inc/node';

const workos = new WorkOS('{secretKey}');

const session = await workos.passwordless.createSession({
  email: '[email protected]{foo-corp.com}',
  type: 'MagicLink',
});

Response

Switch
Copy
1
2
3
4
5
6
7
{
  "id": "passwordless_session_01EHDAK2BFGWCSZXP9HGZ3VK8C",
  "email": "[email protected]{foo-corp.com}",
  "expires_at": "2020-08-13T05:50:00.000Z",
  "link": "https://auth.workos.com/passwordless/token/confirm",
  "object": "passwordless_session",
}

Email a Magic Link

Email a user the Magic Link confirmation URL.

Endpoint

POST

/passwordless/sessions/:id/send

Endpoint

Returns

A boolean confirming the Magic Link was sent.

Email a Magic Link

Switch
Copy
1
2
3
4
5
6
7
import WorkOS from '@workos-inc/node';

const workos = new WorkOS('{secretKey}');

await workos.passwordless.sendSession(
  'passwordless_session_01EHDAK2BFGWCSZXP9HGZ3VK8C'
);

Response

Switch
Copy
1
2
3
{
  "success": true
}

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.

Endpoints

GET

/directories/:id

GET

/directories

DELETE

/directories/:id

GET

/directory_users

GET

/directory_users/:id

GET

/directory_groups

GET

/directory_groups/:id

Directory

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.

Attributes

  • id

    string

    Unique identifier for the Directory.

  • domain

    string

    The URL associated with an Enterprise Client.

  • name

    string

    The name of the directory.

  • organization_id

    string

    (optional)

    The unique identifier for the Organization in which the directory resides.

  • state

    enum

    Describes whether the Directory has been successfully connected to an external provider.

      Possible values

      • linked
      • unlinked
      • validating
      • deleting
      • invalid_credentials

  • type

    enum

    The type of external Directory Provider integrated with.

      Possible values

      • azure scim v2.0
      • bamboohr
      • breathe hr
      • generic scim v1.1
      • generic scim v2.0
      • gsuite directory
      • jump cloud scim v2.0
      • okta scim v1.1
      • okta scim v2.0
      • rippling
      • workday

  • created_at

    string

    The timestamp when the Directory was created.

  • updated_at

    string

    The timestamp when the Directory was last updated.

Directory Object

Copy
{
  "{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 a Directory

Get the details of an existing directory.

Endpoint

GET

/directories/:id

Path Parameters

  • id

    string

    The unique identifier of the Directory.

Returns

A Directory.

Get a Directory

Switch
Copy
1
2
3
4
5
import WorkOS from '@workos-inc/node';

const workos = new WorkOS('{secretKey}');

const directories = await workos.directorySync.getDirectory('directory_01ECAZ4NV9QMV47GW873HDCX74');

Response

Switch
Copy
1
2
3
4
5
6
7
8
9
10
{
  "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",
}

List Directories

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

Endpoint

GET

/directories

Query Parameters

  • domain

    string

    (optional)

    The domain of a Directory.

  • search

    string

    (optional)

    Searchable text to match against Directory names.

  • after

    string

    (optional)

    A cursor to use for pagination. after is a Directory object ID that takes the form directory_* and defines your place in the paginated list of Directory objects. after will return all Directories created after the cursor's value.

  • before

    string

    (optional)

    A cursor to use for pagination. before is a Connection object ID that takes the form directory_* and defines your place in the paginated list of Directory objects. before will return all Directories created before the cursor's value.

  • limit

    integer

    (optional)

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

Returns

An object containing Directories.

  • data

    array of objects

    Array of Directories in descending order by created_at timestamp.

  • list_metadata

    object

    Contains cursor options to utilize for pagination.

List Directories

Switch
Copy
1
2
3
4
5
import WorkOS from '@workos-inc/node';

const workos = new WorkOS('{secretKey}');

const directories = await workos.directorySync.listDirectories();

Response

Switch
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
  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"
  }
}

Delete a Directory

Delete an existing directory.

Endpoint

DELETE

/directories/:id

Path Parameters

  • id

    string

    The unique identifier of the Directory.

Delete a Directory

Switch
Copy
1
2
3
4
5
import WorkOS from '@workos-inc/node';

const workos = new WorkOS('{secretKey}');

await workos.directorySync.deleteDirectory('directory_01ECAZ4NV9QMV47GW873HDCX74')

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.

Attributes

  • id

    string

    Unique identifier for the Directory User.

  • idp_id

    string

    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.

  • directory_id

    string

    The identifier of the Directory the Directory User belongs to.

  • first_name

    string

    The first name of the user.

  • last_name

    string

    The last name of the user.

  • emails

    array of objects

    The emails of the user.

  • username

    string

    The username of the user.

  • groups

    array of objects

    The groups that the user is a member of.

  • state

    enum

    The state of the user.

      Possible values

      • active
      • suspended
      • inactive

  • custom_attributes

    object

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

  • raw_attributes

    object

    An object containing the data returned from the Directory Provider.

Directory User Object

Copy
{
  "{id}": "directory_user_01E1JG7J09H96KYP8HM9B0G5SJ",
  "{idp_id}": "2836",
  "{directory_id}": "directory_01ECAZ4NV9QMV47GW873HDCX74",
  "{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",
    "raw_attributes": {{DSync raw_attributes}}
  }],
  "state": "active",
  "{custom_attributes}": {
    "department": "Engineering"
  },
  "{raw_attributes}": {{DSync raw_attributes}}
}

Get a Directory User

Get the details of an existing Directory User.

Endpoint

GET

/directory_users/:id

Path Parameters

Returns

A Directory User.

Get a Directory User

Switch
Copy
1
2
3
4
5
import WorkOS from '@workos-inc/node';

const workos = new WorkOS('{secretKey}');

const user = await workos.directorySync.getUser('directory_user_01E64QS50EAY48S0XJ1AA4WX4D');

Response

Switch
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
  "id": "directory_user_01E1JG7J09H96KYP8HM9B0G5SJ",
  "idp_id": "2836",
  "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
  "emails": [{
    "primary": true,
    "type": "work",
    "value": "[email protected]{foo-corp.com}"
  }],
  "first_name": "Marcelina",
  "last_name": "Davis",
  "username": "[email protected]{foo-corp.com}",
  "groups": [{
    "id": "directory_group_01E64QTDNS0EGJ0FMCVY9BWGZT",
    "name": "Engineering",
    "raw_attributes": {{DSync raw_attributes}}
  }],
  "state": "active",
  "custom_attributes": {
    "department": "Engineering"
  },
  "raw_attributes": {{DSync raw_attributes}}
}

List Directory Users

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

Endpoint

GET

/directory_users

Query Parameters

One of directory or group must be provided.

  • directory

    string

    (optional)

    Unique identifier of the WorkOS Directory.

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

  • group

    string

    (optional)

    Unique identifier of the WorkOS Directory Group.

    This value can be obtained from the WorkOS API.

  • after

    string

    (optional)

    A cursor to use for pagination. after is a Directory User object ID that takes the form directory_user_* and defines your place in the paginated list of Directory User objects. after will return all Directory Users created after the cursor's value.

  • before

    string

    (optional)

    A cursor to use for pagination. before is a Directory User object ID that takes the form directory_user_* and defines your place in the paginated list of Directory User objects. before will return all Directory Users created before the cursor's value.

  • limit

    integer

    (optional)

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

Returns

An object containing Directory Users and metadata.

  • data

    array of objects

    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.

  • list_metadata

    object

    Contains cursor options to utilize for pagination.

List Directory Users

Switch
Copy
1
2
3
4
5
6
7
import WorkOS from '@workos-inc/node';

const workos = new WorkOS('{secretKey}');

const users = await workos.directorySync.listUsers({
  directory: 'directory_01ECAZ4NV9QMV47GW873HDCX74',
});

Response

Switch
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
{
  "data": [{
    "id": "directory_user_01E1JJHG3BFJ3FNRRHSFWEBNCS",
    "idp_id": "1902",
    "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
    "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",
      "raw_attributes": {{DSync raw_attributes}}
    }],
    "state": "active",
    "custom_attributes": {
      "department": "Engineering"
    },
    "raw_attributes": {{DSync raw_attributes}}
   },
   {
    "id": "directory_user_01E1JJHG10ANRA2V6PAX3GD7TE",
    "idp_id": "8953",
    "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",
      "raw_attributes": {{DSync raw_attributes}}
    }],
    "state": "active",
    "custom_attributes": {
      "department": "Engineering"
    },
    "raw_attributes": {{DSync raw_attributes}}
  }],
  "object": "list",
  "list_metadata": {
    "after": "directory_user_01E4RH82CC8QAP8JTRCTNDSS4C",
    "before": "directory_user_01E4RH828021B9ZZB8KH8E2Z1W"
  }
}

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.

Attributes

  • id

    string

    Unique identifier for the Directory Group.

  • idp_id

    string

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

  • directory_id

    string

    The identifier of the Directory the Directory Group belongs to.

  • name

    string

    The name of the Directory Group.

  • raw_attributes

    object

    An object containing the data returned from the Directory Provider.

Directory Group Object

Copy
{
  "{id}": "directory_group_01E1JJS84MFPPQ3G655FHTKX6Z",
  "{idp_id}": "02grqrue4294w24",
  "{directory_id}": "directory_01ECAZ4NV9QMV47GW873HDCX74",
  "{name}": "Developers",
  "{raw_attributes}": {{DSync raw_attributes}}
}

Get a Directory Group

Get the details of an existing Directory Group.

Endpoint

GET

/directory_groups/:id

Path Parameters

Returns

A Directory Group.

Get a Directory Group

Switch
Copy
1
2
3
4
5
import WorkOS from '@workos-inc/node';

const workos = new WorkOS('{secretKey}');

const group = await workos.directorySync.getGroup('directory_group_01E64QTDNS0EGJ0FMCVY9BWGZT');

Response

Switch
Copy
1
2
3
4
5
6
7
{
  "id" : "directory_group_01E64QTDNS0EGJ0FMCVY9BWGZT",
  "idp_id": "02grqrue4294w24",
  "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
  "name" : "Developers",
  "raw_attributes": {{DSync raw_attributes}}
}

List Directory Groups

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

Endpoint

GET

/directory_groups

Query Parameters

One of directory or user must be provided.

  • directory

    string

    (optional)

    Unique identifier of the WorkOS Directory.

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

  • user

    string

    (optional)

    Unique identifier of the WorkOS Directory User.

    This value can be obtained from the WorkOS API.

  • after

    string

    (optional)

    A cursor to use for pagination. after is a Directory Group object ID that takes the form directory_group_* and defines your place in the paginated list of Directory Group objects. after will return all Directory Groups created after the cursor's value.

  • before

    string

    (optional)

    A cursor to use for pagination. before is a Directory Group object ID that takes the form directory_group_* and defines your place in the paginated list of Directory Group objects. before will return all Directory Groups created before the cursor's value.

  • limit

    integer

    (optional)

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

Returns

An object containing Directory Groups and metadata.

  • data

    array of objects

    Array of Directory Groups in descending order by created_at timestamp.

  • list_metadata

    object

    Contains cursor options to utilize for pagination.

List Directory Groups

Switch
Copy
1
2
3
4
5
6
7
import WorkOS from '@workos-inc/node';

const workos = new WorkOS('{secretKey}');

const groups = await workos.directorySync.listGroups({
  directory: 'directory_01ECAZ4NV9QMV47GW873HDCX74',
});

Response

Switch
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "id": "wh_34FKJ843CVE8F7BXQSPFH0M53V",
  "data" : [{
    "id" : "directory_group_01E1JJS84MFPPQ3G655FHTKX6Z",
    "idp_id": "02grqrue4294w24",
    "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
    "name" : "Developers",
    "raw_attributes": {{DSync raw_attributes}}
  }],
  "list_metadata" : {
    "after" : "directory_group_01E1JJS84MFPPQ3G655FHTKX6Z",
    "before" : "directory_group_01E1JJS84MFPPQ3G655FHTKX6Z"
  }
}

Audit Trail

The Audit Trail API supports publishing and fetching Audit Trail Events.

Endpoints

POST

/events

GET

/events

Audit Trail Event

Audit Events are objects containing information relevant to notable actions taken by users in your application. For example, when a user successfully logs in, a user.login_succeeded Event object is created that contains attributes such as the actor_name of the user who performed the action as well as the location and datetime the event occurred_at.

Attributes

  • id

    string

    Unique identifier for the Audit Trail Event.

  • object

    string

    String representing the object's type. Currently the only possible value is event.

  • action

    object

    Specific activity performed by the actor.

  • actor_id

    string

    Unique identifier of the entity performing the action.

  • actor_name

    string

    Display name of the entity performing the action.

  • group

    string

    A single domain containing related members. This will normally be the customer of a vendor's application. Note that group must be a valid domain name.

  • location

    string

    Identifier for where the Event originated. This will be an IP address (IPv4 or IPv6), hostname, or device ID.

  • metadata

    object

    (optional)

    Arbitrary key-value data containing information associated with the Event.

    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.

  • occurred_at

    date

    ISO-8601 datetime at which the Event happened, with millisecond precision.

  • target_id

    string

    Unique identifier of the object or resource being acted upon.

  • target_name

    string

    Display name of the object or resource that is being acted upon.

Audit Trail Event Object

Copy
{
  "{id}": "evt_01ECQK8C5X4D8FHAK35W6J9PXD",
  "{object}": "event",
  "{action}": {
    "id": "evt_action_01DQX7EX39R54GXQ2NBBTSB608",
    "object": "event_action",
    "name": "user.login_succeeded",
    "environment_id": "environment_01EVEQ8GWZDERGY2MX47ZE2KAB"
  },
  "{actor_id}": "user_01DEQWZNQT8Y47HDPSJKQS1J3F",
  "{actor_name}": "Annie Easley",
  "{group}": "{foo-corp.com}",
  "{location}": "65.215.8.114",
  "{occurred_at}": "2020-07-08T15:41:13.607Z",
  "metadata": {
    "redirect": "/setup",
    "description": "User login succeeded.",
    "x_request_id": "ba7380eb-8cea-4b65-bbb1-4091e5bd76fc"
  },
  "{target_id}": "user_01DEQWZNQT8Y47HDPSJKQS1J3F",
  "{target_name}": "[email protected]{foo-corp.com}",
}

Publish an Audit Event

Create an Audit Event.

Endpoint

POST

/events

Headers

  • Idempotency-Key

    string

    (optional)

    This enables you to retry a request and know that the same operation isn't performed twice. For example, consider: you're publishing an Event, a network connection error interrupts your API request, and you don't receive a response. You can perform the request again using the same idempotency key, guaranteeing that you only publish one Event.

    We suggesting using V4 UUIDs for idempotency keys to ensure unique key values and avoid collisions.

    Idempotency keys expire after 24 hours, so we generate a new request if you reuse a key outside of that time frame.

Body Parameters

  • group

    string

    A single domain containing related members. This will normally be the domain of the Enterprise Client.

  • action

    object

    Specific activity performed by the actor.

  • action_type

    string

    The type of action performed. We recommend values that correspond to Create, Read, Update, and Delete, however any string is accepted.

  • actor_id

    string

    Unique identifier of the entity performing the action.

  • actor_name

    string

    Display name of the entity performing the action.

  • occurred_at

    date

    ISO-8601 datetime at which the Event happened, with millisecond precision.

  • location

    string

    Identifier for where the Event originated. This will be an IP address (IPv4 or IPv6), hostname, or device ID.

  • metadata

    object

    (optional)

    Arbitrary key-value data containing information associated with the Event.

    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_id

    string

    Unique identifier of the object or resource being acted upon.

  • target_name

    string

    Display name of the object or resource that is being acted upon.

Returns

A boolean confirming the event was created.

Publish an Audit Event

Switch
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
import WorkOS from '@workos-inc/node';

const workos = new WorkOS('{secretKey}');

const event = {
  action_type: 'r',
  action: 'user.login_succeeded',
  actor_id: 'user_01DEQWZNQT8Y47HDPSJKQS1J3F',
  actor_name: 'Annie Easley',
  group: '{foo-corp.com}',
  location: '65.215.8.114',
  occurred_at: new Date(),
  target_id: 'user_01DEQWZNQT8Y47HDPSJKQS1J3F',
  target_name: '[email protected]{foo-corp.com}'
};

workos.auditTrail.createEvent(event, { idempotency: '6d4c7400-d4bf-4623-a301-afe7b50569d3' });

Response

Switch
Copy
1
2
3
{
  "success": true
}

List Audit Events

Get a list of all Audit Events matching the criteria specified.

Endpoint

GET

/events

Query Parameters

  • action

    array of strings

    (optional)

    Array of specific activities performed by the actor to filter for.

  • action_type

    array of strings

    (optional)

    Array of action types to filter for.

  • actor_id

    array of strings

    (optional)

    Array of unique identifiers to filter for. An Actor ID is a unique, machine-readable identifier for the entity performing the action.

  • actor_name

    array of strings

    (optional)

    Array of actor names to filter for. An Actor Name is a human-readable label for the entity performing the action.

  • after

    string

    (optional)

    A cursor to use for pagination. after is an Event object ID that takes the form evt_* and defines your place in the paginated list of Event objects. after will return all Events created after the cursor's value.

  • before

    string

    (optional)

    A cursor to use for pagination. before is an Event object ID that takes the form evt_* and defines your place in the paginated list of Event objects. before will return all Events created before the cursor's value.

  • group

    array of strings

    (optional)

    Array of groups to filter events for. A Group is a single domain containing related members. This will normally be the domain of the Enterprise Client.

  • limit

    integer

    (optional)

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

  • occurred_at

    date

    (optional)

    ISO-8601 datetime to filter for when an Event occurred, with millisecond precision.

  • occurred_at_gt

    date

    (optional)

    ISO-8601 datetime to filter for when an Event occurred after, with millisecond precision.

  • occurred_at_gte

    date

    (optional)

    ISO-8601 datetime to filter for when an Event occurred at or after, with millisecond precision.

  • occurred_at_lt

    date

    (optional)

    ISO-8601 datetime to filter for when an Event occurred before, with millisecond precision.

  • occurred_at_lte

    date

    (optional)

    ISO-8601 datetime to filter for when an Event occurred at or before, with millisecond precision.

  • search

    string

    (optional)

    Keyword string to filter for.

  • target_id

    array of strings

    (optional)

    Array of target IDs to filter for. A Target ID is a unique identifier of the object or resource being acted upon.

  • target_name

    array of strings

    (optional)

    Array of target names to filter for. A Target Name is a display name of the object or resource that is being acted upon.

Returns

An object containing Audit Trail Events and metadata.

  • data

    array of objects

    Array of Audit Trail Events in descending order by created_at timestamp.

  • list_metadata

    object

    Contains cursor options to utilize for pagination.

List Audit Events

Switch
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
import WorkOS from '@workos-inc/node';

const workos = new WorkOS('{secretKey}');

await workos.auditTrail.listEvents({
  limit: '1',
  before: 'evt_01ECQKC8JA3T7Z1C9QZKBB1BEH',
  action: ['user.login_succeeded'],
  action_type: ['r'],
  actor_name: ['annie'],
  actor_id: ['user_01DEQWZNQT8Y47HDPSJKQS1J3F'],
  group: ['{foo-corp.com}'],
  occurred_at: new Date(),
  metadata: null,
  target_id: ['user_01DEQWZNQT8Y47HDPSJKQS1J3F'],
  target_name: ['[email protected]{foo-corp.com}']
});

Response

Switch
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
  "data": [{
    "id": "evt_01ECQK8C5X4D8FHAK35W6J9PXD",
    "object": "event",
    "action": {
      "id": "evt_action_01DQX7EX39R54GXQ2NBBTSB608",
      "object": "event_action",
      "name": "user.login_succeeded",
      "environment_id": "environment_01EVEQ8GWZDERGY2MX47ZE2KAB"
    },
    "actor_id": "user_01DEQWZNQT8Y47HDPSJKQS1J3F",
    "actor_name": "Annie Easley",
    "group": "{foo-corp.com}",
    "location": "65.215.8.114",
    "metadata": {
      "redirect": "/setup",
      "description": "User login succeeded.",
      "x_request_id": "ba7380eb-8cea-4b65-bbb1-4091e5bd76fc"
    },
    "occurred_at": "2020-07-08T15:41:13.607Z",
    "target_id": "user_01DEQWZNQT8Y47HDPSJKQS1J3F",
    "target_name": "[email protected]{foo-corp.com}",
    "type": "r"
  }],
  "list_metadata": {
    "after": "evt_01ECQK8C5X4D8FHAK35W6J9PXD",
    "before": "evt_01EKN884KEDQNQZEBPCQNV1XXD"
  }
}

Connection 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, just to name a few examples. Each Event contains specific information explaining what happened to trigger the webhook.

Event Types

  • connection.activated

    Triggers when a Connection's state changes to active.

  • connection.deactivated

    Triggers when a Connection's state changes to inactive.

  • connection.deleted

    Triggers when a Connection is deleted.

    NOTE: The connection's state in the payload indicates the state before the deletion occurs and can be ignored.

connection.activated

Copy
{
  "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.activated"
}

connection.deactivated

Copy
{
  "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.deactivated"
}

connection.deleted

Copy
{
  "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",
  },
  "event": "connection.deleted"
}

Directory Webhooks

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

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. Each time there is a change, WorkOS makes a request to your application's webhook URL containing an Event. Each Event contains specific information explaining what happened to trigger the webhook.

Event Types

  • dsync.activated

    Triggers when a Directory's state changes to active.

  • dsync.deactivated

    Triggers when a Directory's state changes to inactive.

  • dsync.deleted

    Triggers when a Directory is deleted.

    NOTE: The directory's state in the payload indicates the state before the deletion occurs and can be ignored.

dsync.activated

Copy
{
  "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.activated"
}

dsync.deactivated

Copy
{
  "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.deactivated"
}

dsync.deleted

Copy
{
  "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",
  },
  "event": "dsync.deleted"
}

Directory User Webhooks

WorkOS uses webhooks to automatically notify your application any time certain changes are made to Users or Groups in an Enterprise Client's Directory.

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. 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 users are created, updated, or deleted. Each Event contains specific information explaining what happened to trigger the webhook.

Event Types

  • dsync.user.created

    Triggers when a user is created or added to the directory

  • dsync.user.updated

    Triggers when a user's properties have been updated.

  • dsync.user.deleted

    Triggers when a user has been removed from a directory.

Previous Attributes

The payload for dsync.user.updated webhooks shows changes between Directory User snapshots in a previous_attributes property. (Theprevious_attributes property is an object containing the names and values of attributes and their previous values.) 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.

dsync.user.created

Copy
{
  "id": "wh_07FKJ843CVE8F7BXQSPFH0M53V",
  "data": {
    "id": "directory_user_01E1X1B89NH8Z3SDFJR4H7RGX7",
    "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
    "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",
    "custom_attributes": {
      "department": "Engineering"
    },
    "raw_attributes": {{DSync raw_attributes}}
  },
  "event": "dsync.user.created"
}

dsync.user.updated

Copy
{
  "id": "wh_08FKJ843CVE8F7BXQSPFH0M53V",
  "data": {
    "id": "directory_user_01E1X1B89NH8Z3SDFJR4H7RGX7",
    "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
    "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",
    "custom_attributes": {
      "department": "Engineering"
    },
    "raw_attributes": {{DSync raw_attributes}},
    "previous_attributes": {{DSync previous_attributes}}
  },
  "event": "dsync.user.updated"
}

dsync.user.deleted

Copy
{
  "id": "wh_09FKJ843CVE8F7BXQSPFH0M53V",
  "data": {
    "id": "directory_user_01E1X1B89NH8Z3SDFJR4H7RGX7",
    "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
    "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",
    "custom_attributes": {
      "department": "Engineering"
    },
    "raw_attributes": {{DSync raw_attributes}}
  },
  "event": "dsync.user.deleted"
}

Directory Group Webhooks

WorkOS uses webhooks to automatically notify your application any time certain changes are made Groups in an Enterprise Client's Directory.

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 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 group properties are updated, or users have been added to a group, just to name a few examples. Each Event contains specific information explaining what happened to trigger the webhook.

Event Types

  • dsync.group.created

    Triggers when a group is created or added to a directory.

  • dsync.group.updated

    Triggers when a group's properties have been updated.

  • dsync.group.user_added

    Triggers when a user has been added to a group.

  • dsync.group.user_removed

    Triggers when a user has been removed from a group.

  • dsync.group.deleted

    Triggers when a group is removed from a directory.

Previous Attributes

The payload for dsync.group.updated webhooks shows changes between Directory Group snapshots in a previous_attributes property. (Theprevious_attributes property is an object containing the names and values of attributes and their previous values.) 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.

dsync.group.created

Copy
{
  "id": "wh_44FKJ843CVE8F7BXQSPFH0M53V",
  "data": {
    "id": "directory_group_01E1X5GPMMXF4T1DCERMVEEPVW",
    "idp_id": "02grqrue4294w24",
    "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
    "name": "Developers",
    "raw_attributes": {{DSync raw_attributes}}
  },
  "event": "dsync.group.created"
}

dsync.group.updated

Copy
{
  "id": "wh_54FKJ843CVE8F7BXQSPFH0M53V",
  "data": {
    "id": "directory_group_01E1X5GPMMXF4T1DCERMVEEPVW",
    "idp_id": "02grqrue4294w24",
    "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
    "name": "Developers",
    "raw_attributes": {{DSync raw_attributes}},
    "previous_attributes": {{DSync previous_attributes}}
  },
  "event": "dsync.group.updated"
}

dsync.group.user_added

Copy
{
  "id": "wh_04FKJ843CVE8F7BXQSPFH0M53V",
  "data": {
    "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
    "user": {
      "id": "directory_user_01E1X56GH84T3FB41SD6PZGDBX",
      "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",
      "custom_attributes": {
        "department": "Engineering"
      },
      "raw_attributes": {{DSync raw_attributes}}
    },
    "group": {
      "id": "directory_group_01E1X5GPMMXF4T1DCERMVEEPVW",
      "name": "Developers"
    }
  },
  "event": "dsync.group.user_added"
}

dsync.group.user_removed

Copy
{
  "id": "wh_05FKJ843CVE8F7BXQSPFH0M53V",
  "event": "dsync.group.user_removed",
  "data": {
    "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
    "user": {
      "id": "directory_user_01E1X56GH84T3FB41SD6PZGDBX",
      "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",
      "custom_attributes": {
        "department": "Engineering"
      },
      "raw_attributes": {{DSync raw_attributes}}
    },
    "group": {
      "id": "directory_group_01E1X5GPMMXF4T1DCERMVEEPVW",
      "name": "Developers"
    }
  }
}

dsync.group.deleted

Copy
{
  "id": "wh_06FKJ843CVE8F7BXQSPFH0M53V",
  "data": {
    "id": "directory_group_01E1X5GPMMXF4T1DCERMVEEPVW",
    "idp_id": "02grqrue4294w24",
    "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
    "name": "Developers",
    "raw_attributes": {{DSync raw_attributes}}
  },
  "event": "dsync.group.group_deleted"
}

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.

Endpoints

POST

/portal/generate_link

Portal Link

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

Attributes

  • link

    string

    An ephemeral link to initiate the Admin Portal.

Portal Link Object

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

Generate a Portal Link

Generate a Portal Link scoped to an Organization.

Endpoint

POST

/portal/generate_link

Body Parameters

  • organization

    string

    An Organization identifier.

  • intent

    enum

    The intent of the Admin Portal.

      Possible values

      • sso

        Launch Admin Portal for creating SSO connections

      • dsync

        Launch Admin Portal for creating directory sync connections

  • return_url

    string

    (optional)

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

Returns

A Portal Link.

Generate a Portal Link

Switch
Copy
1
2
3
4
5
6
7
8
9
import WorkOS from '@workos-inc/node';

const workos = new WorkOS('{secretKey}');

const { link } = await workos.portal.generateLink({
  organization: 'org_01EHZNVPK3SFK441A1RGBFSHRT',
  intent: 'sso',
  returnUrl: 'https://www.example.com' //optional
});

Response

Switch
Copy
1
2
3
{
  "link": "https://id.workos.com/portal/launch?secret=JteZqfJZqUcgWGaYCC6iI0gW0",
}