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
https://api.workos.com
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 WorkOS 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
1sk_example_123456789
Set API Key
1import WorkOS from '@workos-inc/node';23const workos = new WorkOS('sk_example_123456789');
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
Successful request.
The request was not acceptable, often indicates the parameters were not correct.
The API key used was invalid.
The API key used did not have the correct permissions.
The resource was not found.
Indicates an error with WorkOS' servers.
Pagination
Many top-level resources have support for bulk fetches via "list" API methods. For instance, you can list connections, list directory users, and list directory groups. These list API methods share a common structure, taking at least these three parameters: limit
, 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 descending order by created_at
timestamp. The after
parameter returns objects created after the named object, which occur earlier in the list. The before
parameter returns objects created before the named object, which occur later in the list.
Upper limit on the number of objects to return, between
1
and100
. The default value is10
.A cursor to use for pagination.
after
is an object ID that defines your place in the list. For example, if you make a list request and receive 100 objects, starting withobj_123
, your subsequent call can includeafter=obj_123
to fetch the previous batch of objects created afterobj_123
.A cursor to use for pagination.
before
is an object ID that defines your place in the list. For example, if you make a list request and receive 100 objects, ending withobj_123
, your subsequent call can includebefore=obj_123
to fetch the next batch of objects created beforeobj_123
.
An array of objects in descending order by
created_at
timestamp.Contains cursor options to utilize for pagination.
Response
{"data": [{"object": "connection","id": "conn_01E4ZCR3C56J083X43JQXF3JK5","organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY","connection_type": "GoogleOAuth","name": "Foo Corp","state": "active","created_at": "2021-06-25T19:07:33.155Z","updated_at": "2021-06-25T19:08:33.155Z",},{"object": "connection","id": "conn_01E2NPPCT7XQ2MVVYDHWGK1WN4","organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY","connection_type": "OktaSAML","name": "Example Co","state": "active","created_at": "2021-06-25T19:09:33.155Z","updated_at": "2021-06-25T19:10:33.155Z",}],"list_metadata": {"before": "conn_01E2NPPCT7XQ2MVVYDHWGK1WN4","after": null,}}
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.
Unique identifier for the Organization.
The name of the Organization.
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.
The timestamp when the Organization was created.
The timestamp when the Organization was last updated.
List of Organization Domains.
Endpoints
Organization Object
{"object": "organization",{"id": "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A","object": "organization_domain","domain": "foo-corp.com"},]}
Get an Organization
Get the details of an existing organization.
/organizations/:id
The unique identifier of the Organization.
An Organization.
Get an Organization
1import WorkOS from '@workos-inc/node';23const workos = new WorkOS('sk_example_123456789');45const organization = await workos.organizations.getOrganization('org_01EHZNVPK3SFK441A1RGBFSHRT');
Response
1{2 "id": "org_01EHZNVPK3SFK441A1RGBFSHRT",3 "object": "organization",4 "name": "Foo Corporation",5 "allow_profiles_outside_organization": false,6 "created_at": "2021-06-25T19:07:33.155Z",7 "updated_at": "2021-06-25T19:07:33.155Z",8 "domains": [9 {10 "domain": "foo-corp.com",11 "id": "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A",12 "object": "organization_domain"13 },14 {15 "domain": "another-foo-corp-domain.com",16 "id": "org_domain_01EHZNS0H9W90A90FV79GAB6AB",17 "object": "organization_domain"18 }19 ]20}
List Organizations
Get a list of all of your existing organizations matching the criteria specified.
/organizations
The domains of an Organization. Any Organization with a matching domain will be returned.
A cursor to use for pagination.
after
is an Organization object ID that takes the formorg_*
and defines your place in the paginated list of Organization objects.after
will return all Organizations created after the cursor's value.A cursor to use for pagination.
before
is an Organization object ID that takes the formorg_*
and defines your place in the paginated list of Organization objects.before
will return all Organizations created before the cursor's value.Upper limit on the number of Organizations to return, between
1
and100
. The default value is10
.
An object containing Organizations.
Array of Organizations in descending order by
created_at
timestamp.Contains cursor options to utilize for pagination.
List Organizations
1import WorkOS from '@workos-inc/node';23const workos = new WorkOS('sk_example_123456789');45const organizations = await workos.organizations.listOrganizations({6 domains: ['foo-corp.com']7});
Response
1{2 "data": [3 {4 "id": "org_01EHZNVPK3SFK441A1RGBFSHRT",5 "object": "organization",6 "name": "Foo Corp",7 "allow_profiles_outside_organization": false,8 "created_at": "2021-06-25T19:07:33.155Z",9 "updated_at": "2021-06-25T19:07:33.155Z",10 "domains": [11 {12 "domain": "foo-corp.com",13 "id": "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A",14 "object": "organization_domain"15 },16 {17 "domain": "another-foo-corp-domain.com",18 "id": "org_domain_01EHZNS0H9W90A90FV79GAB6AB",19 "object": "organization_domain"20 }21 ]22 }23 ],24 "list_metadata": {25 "before": "org_01EHZNVPK3SFK441A1RGBFSHRT",26 "after": "org_01EJBGJT2PC6638TN5Y380M40Z",27 }28}
Create an Organization
Create an Organization with a set of domains.
/organizations
The name of the Organization.
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.
The domains of the Organization.
At least one domain is required unless
allow_profiles_outside_organization
istrue
.
An Organization object.
Create an Organization
1import WorkOS from '@workos-inc/node';23const workos = new WorkOS('sk_example_123456789');45const organization = await workos.organizations.createOrganization({6 name: 'Foo Corp',7 domains: ['foo-corp.com']8});
Response
1{2 "id": "org_01EHZNVPK3SFK441A1RGBFSHRT",3 "object": "organization",4 "name": "Foo Corp",5 "allow_profiles_outside_organization": false,6 "created_at": "2021-06-25T19:07:33.155Z",7 "updated_at": "2021-06-25T19:07:33.155Z",8 "domains": [9 {10 "domain": "foo-corp.com",11 "id": "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A",12 "object": "organization_domain"13 },14 {15 "domain": "another-foo-corp-domain.com",16 "id": "org_domain_01EHZNS0H9W90A90FV79GAB6AB",17 "object": "organization_domain"18 }19 ]20}
Update an Organization
Update an Organization.
/organizations/:id
The name of the Organization.
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.
The domains of the Organization.
At least one domain is required unless
allow_profiles_outside_organization
istrue
.
An Organization object.
Update an Organization
1import WorkOS from '@workos-inc/node';23const workos = new WorkOS('sk_example_123456789');45const organization = await workos.organizations.updateOrganization({6 organization: 'org_01EHZNVPK3SFK441A1RGBFSHRT',7 name: 'Foo Corp',8 domains: ['foo-corp.com']9});
Response
1{2 "id": "org_01EHZNVPK3SFK441A1RGBFSHRT",3 "object": "organization",4 "name": "Foo Corporation",5 "allow_profiles_outside_organization": false,6 "created_at": "2021-06-25T19:07:33.155Z",7 "updated_at": "2021-06-25T19:08:33.155Z",8 "domains": [9 {10 "domain": "foo-corp.com",11 "id": "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A",12 "object": "organization_domain"13 },14 {15 "domain": "another-foo-corp-domain.com",16 "id": "org_domain_01EHZNS0H9W90A90FV79GAB6AB",17 "object": "organization_domain"18 }19 ]20}
Delete an Organization
Delete an existing organization.
/organizations/:id
The unique identifier of the Organization.
Delete an Organization
1import WorkOS from '@workos-inc/node';23const workos = new WorkOS('sk_example_123456789');45await 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.
Unique identifier for the Organization Domain.
Domain for the Organization Domain.
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
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.
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.
/sso/authorize
This value can be obtained from the SSO Configuration page in the WorkOS dashboard.
The only valid option for the
response_type
parameter iscode
.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.A Redirect URI to return an authorized user to.
The
connection
connection selector is used to initiate SSO for a Connection.The value of this parameter should be a WorkOS Connection ID.
For example, the Developer can persist the WorkOS Connection ID with application User or Team identifiers. WorkOS will use the Connection indicated by the
connection
parameter to direct the user to the corresponding IdP for authentication.The
organization
connection selector is used to initiate SSO for an Organization.The value of this parameter should be a WorkOS Organization ID.
For example, the Developer can persist the WorkOS Organization ID with application User or Team identifiers. WorkOS will use the
organization
connection selector to determine the appropriate Connection and IdP to direct the user to for authentication.Note that the Organization must only have a single active SSO Connection, otherwise an
ambiguous_connection_selector
error code will be returned.The
provider
connection selector is used to initiate SSO using an OAuth provider.Currently, the only supported values for
provider
areGoogleOAuth
andMicrosoftOAuth
. Provide theprovider
parameter when authenticating Google OAuth users, because Google OAuth does not take a user's domain into account when logging in with a "Sign in with Google" button.Optional parameter that a Developer can choose to include in their authorization URL. If included, then the redirect URI received from WorkOS will contain the exact
state
that was passed in the authorization URL.The
state
parameter can be used to encode arbitrary information to help restore application state between redirects.Can be used to pre-fill the username/email address field of the IdP sign-in page for the user, if you know their username ahead of time.
Currently, this parameter is only supported for
OAuth
, andOpenID Connect
connection types.
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.
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.
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 theconnection
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.
organization_invalid
There is no Organization 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
, orprovider
.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.
Possible values
Get Authorization URL
1import WorkOS from '@workos-inc/node';23const workos = new WorkOS('sk_example_123456789');45workos.sso.getAuthorizationURL({6 connection: 'conn_01E4ZCR3C56J083X43JQXF3JK5',7 clientID: 'client_123456789',8 redirectURI: 'https://your-app.com/callback',9 state: 'dj1kUXc0dzlXZ1hjUQ==',10});
Response
1https://api.workos.com/sso/authorize?2 response_type=code&3 client_id=client_123456789&4 redirect_uri=https://your-app.com/callback&5 connection=conn_01E4ZCR3C56J083X43JQXF3JK5&6 state=dj1kUXc0dzlXZ1hjUQ==
Redirect URI
1https://your-app.com/callback?2 code=01E2RJ4C05B52KKZ8FSRDAP23J&3 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.
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.
String representing the object's type. Currently the only possible value is
profile
.Unique identifier for the Connection to which the Profile belongs.
Unique identifier for the Organization in which the Connection resides.
The type of SSO Connection used to authenticate the user.
ADFSSAML
Auth0SAML
AzureSAML
CASSAML
CloudflareSAML
CyberArkSAML
ClassLinkSAML
DuoSAML
GenericOIDC
GenericSAML
GoogleOAuth
GoogleSAML
JumpCloudSAML
KeycloakSAML
LastPassSAML
MicrosoftOAuth
MiniOrangeSAML
NetIqSAML
OktaSAML
OneLoginSAML
OracleSAML
PingFederateSAML
PingOneSAML
SalesforceSAML
SimpleSamlPhpSAML
VMwareSAML
Possible values
The user's email address.
The user's first name.
The user's last name.
Unique identifier for the user, assigned by the Identity Provider. Different Identity Providers use different ID formats.
One possible use case for
idp_id
is associating a user’s SSO Profile with any relevant Directory Sync actions related to that user.Object of key-value pairs containing relevant user data from the Identity Provider.
Raw attributes are an extended set of information one can expect for each user Profile. These raw attributes will vary by Identity Provider and Identity Provider configuration.
Profile Object
{"connection_id": "conn_01E4ZCR3C56J083X43JQXF3JK5","organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY","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.
/sso/token
This value can be obtained from the SSO Configuration page in the WorkOS dashboard.
This is the same value as the WorkOS Environment’s secret API key.
This value can be obtained from the API Keys page in the WorkOS dashboard.
The method by which your application will receive an access token. This value should be
authorization_code
.The authorization value which was passed back as a query parameter in the callback to the redirect URI.
An object containing an access token and Profile.
An access token that can be exchanged for a user profile. Access tokens are one-time use and expire 10 minutes after they’re created.
The user Profile.
Get a Profile
1import WorkOS from '@workos-inc/node';23const workos = new WorkOS('sk_example_123456789');45await workos.sso.getProfileAndToken({6 code,7 clientID: 'client_123456789',8});
Response
1{2 "access_token": "01DMEK0J53CVMC32CK5SE0KZ8Q",3 "profile": {4 "id": "prof_01DMC79VCBZ0NY2099737PSVF1",5 "connection_id": "conn_01E4ZCR3C56J083X43JQXF3JK5",6 "connection_type": "okta",8 "first_name": "Todd",9 "idp_id": "00u1a0ufowBJlzPlk357",10 "last_name": "Rundgren",11 "object": "profile",12 "raw_attributes": {...}13 }14}
Get a User Profile
Exchange an access_token
for a user's Profile. Because this profile is returned in the Get a Profile and Token endpoint your application usually does not need to call this endpoint. It is available for any authentication flows that require an additional endpoint to retrieve a user's profile.
/sso/profile
The authorization value which was returned along with the profile when calling the Get a Profile and Token endpoint.
A user profile.
The user Profile.
Get a User Profile
1import WorkOS from '@workos-inc/node';23const workos = new WorkOS('sk_example_123456789');45await workos.sso.getProfile({6 accessToken: '01DMEK0J53CVMC32CK5SE0KZ8Q',7});
Response
1{2 "id": "prof_01DMC79VCBZ0NY2099737PSVF1",3 "connection_id": "conn_01E4ZCR3C56J083X43JQXF3JK5",4 "connection_type": "okta",6 "first_name": "Todd",7 "idp_id": "00u1a0ufowBJlzPlk357",8 "last_name": "Rundgren",9 "object": "profile",10 "raw_attributes": {...}11}
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.
String representing the object's type. Currently the only possible value is
connection
.Unique identifier for the Connection.
Unique identifier for the Organization in which the Connection resides.
The type of SSO Connection used to authenticate a user.
One possible use case for
connection_type
is dynamically generating authorization URLs.ADFSSAML
ADPOIDC
Auth0SAML
AzureSAML
CASSAML
ClassLinkSAML
CloudflareSAML
CyberArkSAML
DuoSAML
GenericOIDC
DuoSAML
GenericSAML
GoogleOAuth
GoogleSAML
JumpCloudSAML
KeycloakSAML
LastPassSAML
MicrosoftOAuth
MiniOrangeSAML
NetIqSAML
OktaSAML
OneLoginSAML
OracleSAML
PingFederateSAML
PingOneSAML
SalesforceSAML
SimpleSamlPhpSAML
ShibbolethSAML
ShibbolethGenericSAML
VMwareSAML
Possible values
A human-readable name for the Connection. This will most commonly be the Enterprise Client's name.
Indicates whether a Connection is able to authenticate users.
draft
active
inactive
Possible values
The timestamp when the Connection was created.
The timestamp when the Connection was last updated.
Connection Object
{"organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",}
Get a Connection
Get the details of an existing connection.
/connections/:id
The unique identifier of the Connection.
A Connection.
Get a Connection
1import WorkOS from '@workos-inc/node';23const workos = new WorkOS('sk_example_123456789');45const connection = await workos.sso.getConnection('conn_01E4ZCR3C56J083X43JQXF3JK5');
Response
1{2 "object": "connection",3 "id": "conn_01E4ZCR3C56J083X43JQXF3JK5",4 "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",5 "connection_type": "GoogleOAuth",6 "name": "Foo Corp",7 "state": "active",8 "created_at": "2021-06-25T19:07:33.155Z",9 "updated_at": "2021-06-25T19:07:33.155Z",10 "domains": [11 {12 "id": "conn_domain_01EHWNFTAFCF3CQAE5A9Q0P1YB",13 "object": "connection_domain",14 "domain": "foo-corp.com"15 }16 ]17}
List Connections
Get a list of all of your existing connections matching the criteria specified.
/connections
A cursor to use for pagination.
after
is a Connection object ID that takes the formconn_*
and defines your place in the paginated list of Connection objects.after
will return all Connections created after the cursor's value.A cursor to use for pagination.
before
is a Connection object ID that takes the formconn_*
and defines your place in the paginated list of Connection objects.before
will return all Connections created before the cursor's value.Filter Connections by their type.
ADFSSAML
Auth0SAML
AzureSAML
CyberArkSAML
CloudflareSAML
CASSAML
ClassLinkSAML
DuoSAML
GenericOIDC
GenericSAML
GoogleOAuth
GoogleSAML
JumpCloudSAML
KeycloakSAML
LastPassSAML
MicrosoftOAuth
MiniOrangeSAML
NetIqSAML
OktaSAML
OneLoginSAML
OracleSAML
PingFederateSAML
PingOneSAML
SalesforceSAML
SimpleSamlPhpSAML
VMwareSAML
Possible values
Filter Connections by their associated domain.
Filter Connections by their associated organization.
Upper limit on the number of Connections to return, between
1
and100
. The default value is10
.
An object containing Connections and metadata.
An array of Connections in descending order by
created_at
timestamp.Contains cursor options to utilize for pagination.
List Connections
1import WorkOS from '@workos-inc/node';23const workos = new WorkOS('sk_example_123456789');45const connections = await workos.sso.listConnections();
Response
1{2 "data": [3 {4 "object": "connection",5 "id": "conn_01E4ZCR3C56J083X43JQXF3JK5",6 "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",7 "connection_type": "GoogleOAuth",8 "name": "Foo Corp",9 "state": "active",10 "created_at": "2021-06-25T19:07:33.155Z",11 "updated_at": "2021-06-25T19:08:33.155Z",12 },13 {14 "object": "connection",15 "id": "conn_01E2NPPCT7XQ2MVVYDHWGK1WN4",16 "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",17 "connection_type": "OktaSAML",18 "name": "Example Co",19 "state": "active",20 "created_at": "2021-06-25T19:09:33.155Z",21 "updated_at": "2021-06-25T19:10:33.155Z",22 }23 ],24 "list_metadata": {25 "before": "conn_01E2NPPCT7XQ2MVVYDHWGK1WN4",26 "after": null,27 }28}
Delete a Connection
Delete an existing connection.
/connections/:id
The unique identifier of the Connection.
Delete a Connection
1import WorkOS from '@workos-inc/node';23const workos = new WorkOS('sk_example_123456789');45await workos.sso.deleteConnection('conn_01E2NPPCT7XQ2MVVYDHWGK1WN4')
Endpoints
Passwordless Session
An object representing a passwordless authentication session.
The unique ID of the session.
The email address of the user for the session.
The ISO-8601 datetime at which the session expires.
The link for the user to authenticate with. You can use this link to send a custom email to the user, or send an email using Email a Magic Link to the user.
Once a user has authenticated with the link, WorkOS issues a redirect to the Environment's default redirect URI, with a
code
parameter and, if provided during session creation, astate
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 ofaccess_denied
.String representing the object's type. Currently, the only possible value is
passwordless_session
.
Passwordless Session Object
{}
Create Passwordless Session
Create a Passwordless Session for a Magic Link Connection.
/passwordless/sessions
The email of the user to authenticate.
The type of Passwordless Session to create. Currently, the only supported value is
MagicLink
.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.
Optional parameter that a Developer can choose to include in their authorization URL. If included, it will override the default Redirect URI set in the dashboard. This is the location your user will be redirected to once the session has been completed successfully.
The number of seconds the Passwordless Session should live before expiring.
This value must be between
300
(5 minutes) and1800
(30 minutes), inclusive.Optional parameter that a Developer can choose to include in their authorization URL. If included, then the redirect URI received from WorkOS will contain the exact
state
that was passed in the authorization URL.The
state
parameter can be used to encode arbitrary information to help restore application state between redirects.
Create a Passwordless Session
1import WorkOS from '@workos-inc/node';23const workos = new WorkOS('sk_example_123456789');45const session = await workos.passwordless.createSession({7 type: 'MagicLink',8});
Response
1{2 "id": "passwordless_session_01EHDAK2BFGWCSZXP9HGZ3VK8C",4 "expires_at": "2020-08-13T05:50:00.000Z",5 "link": "https://auth.workos.com/passwordless/token/confirm",6 "object": "passwordless_session",7}
Email a Magic Link
Email a user the Magic Link confirmation URL.
/passwordless/sessions/:id/send
The unique identifier of the Passwordless Session to send an email for.
A boolean
confirming the Magic Link was sent.
Email a Magic Link
1import WorkOS from '@workos-inc/node';23const workos = new WorkOS('sk_example_123456789');45await workos.passwordless.sendSession(6 'passwordless_session_01EHDAK2BFGWCSZXP9HGZ3VK8C'7);
Response
1{2 "success": true3}
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
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.
Unique identifier for the Directory.
The URL associated with an Enterprise Client.
The name of the directory.
The unique identifier for the Organization in which the directory resides.
Describes whether the Directory has been successfully connected to an external provider.
linked
unlinked
validating
deleting
invalid_credentials
Possible values
The type of external Directory Provider integrated with.
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
onelogin scim v2.0
people hr
pingfederate scim v2.0
rippling
workday
Possible values
The timestamp when the Directory was created.
The timestamp when the Directory was last updated.
Directory Object
{}
Get a Directory
Get the details of an existing directory.
/directories/:id
The unique identifier of the Directory.
A Directory.
Get a Directory
1import WorkOS from '@workos-inc/node';23const workos = new WorkOS('sk_example_123456789');45const directories = await workos.directorySync.getDirectory('directory_01ECAZ4NV9QMV47GW873HDCX74');
Response
1{2 "id": "directory_01ECAZ4NV9QMV47GW873HDCX74",3 "domain": "foo-corp.com",4 "name": "Foo Corp",5 "organization_id": "org_01EHZNVPK3SFK441A1RGBFSHRT",6 "state": "unlinked",7 "type": "gsuite directory",8 "created_at": "2021-06-25T19:07:33.155Z",9 "updated_at": "2021-06-25T19:07:33.155Z"10}
List Directories
Get a list of all of your existing directories matching the criteria specified.
/directories
The domain of a Directory.
Searchable text to match against Directory names.
Filter Directories by their associated organization.
A cursor to use for pagination.
after
is a Directory object ID that takes the formdirectory_*
and defines your place in the paginated list of Directory objects.after
will return all Directories created after the cursor's value.A cursor to use for pagination.
before
is a Connection object ID that takes the formdirectory_*
and defines your place in the paginated list of Directory objects.before
will return all Directories created before the cursor's value.Upper limit on the number of Connections to return, between
1
and100
. The default value is10
.
An object containing Directories.
Array of Directories in descending order by
created_at
timestamp.Contains cursor options to utilize for pagination.
List Directories
1import WorkOS from '@workos-inc/node';23const workos = new WorkOS('sk_example_123456789');45const directories = await workos.directorySync.listDirectories();
Response
1{2 data: [{3 "id": "directory_01ECAZ4NV9QMV47GW873HDCX74",4 "domain": "foo-corp.com",5 "name": "Foo Corp",6 "organization_id": "org_01EHZNVPK3SFK441A1RGBFSHRT",7 "object": "directory",8 "state": "unlinked",9 "type": "gsuite directory",10 "created_at": "2021-06-25T19:07:33.155Z",11 "updated_at": "2021-06-25T19:08:33.155Z"12 },13 {14 "id": "directory_01E8CS3GSBEBZ1F1CZAEE3KHDG",15 "domain": "foo-corp.com",16 "external_key": "r3NDlInUnAe6i4wG",17 "name": "Foo Corp",18 "organization_id": "org_01EHZNVPK3SFK441A1RGBFPANT",19 "object": "directory",20 "state": "linked",21 "type": "okta scim v2.0",22 "created_at": "2021-06-25T19:09:33.155Z",23 "updated_at": "2021-06-25T19:10:33.155Z"24 }],25 "list_metadata" : {26 "after" : "directory_01E1JJS84MFPPQ3G655FHTKX6Z",27 "before" : "directory_01E1JJS84MFPPQ3G655FHTKX6Z"28 }29}
Delete a Directory
Delete an existing directory.
/directories/:id
The unique identifier of the Directory.
Delete a Directory
1import WorkOS from '@workos-inc/node';23const workos = new WorkOS('sk_example_123456789');45await 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.
Unique identifier for the Directory User.
Unique identifier for the user, assigned by the Directory Provider. Different Directory Providers use different ID formats.
One possible use case for
idp_id
is associating the Directory User with their SSO Profile.The identifier of the Directory the Directory User belongs to.
The first name of the user.
The last name of the user.
The emails of the user.
The username of the user.
The groups that the user is a member of.
The state of the user.
active
suspended
inactive
Possible values
An object containing the custom attribute mapping for the Directory Provider.
An object containing the data returned from the Directory Provider.
Directory User Object
{"primary": true,"type": "work",}],"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","department": "Engineering"},}
Get a Directory User
Get the details of an existing Directory User.
/directory_users/:id
The unique identifier of the Directory User.
Get a Directory User
1import WorkOS from '@workos-inc/node';23const workos = new WorkOS('sk_example_123456789');45const user = await workos.directorySync.getUser('directory_user_01E64QS50EAY48S0XJ1AA4WX4D');
Response
1{2 "id": "directory_user_01E1JG7J09H96KYP8HM9B0G5SJ",3 "idp_id": "2836",4 "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",5 "emails": [{6 "primary": true,7 "type": "work",9 }],10 "first_name": "Marcelina",11 "last_name": "Davis",13 "groups": [{14 "id": "directory_group_01E64QTDNS0EGJ0FMCVY9BWGZT",15 "name": "Engineering",16 "created_at": "2021-06-25T19:07:33.155Z",17 "updated_at": "2021-06-25T19:07:33.155Z",18 "raw_attributes": {...}19 }],20 "state": "active",21 "created_at": "2021-06-25T19:07:33.155Z",22 "updated_at": "2021-06-25T19:07:33.155Z",23 "custom_attributes": {24 "department": "Engineering"25 },26 "raw_attributes": {...}27}
List Directory Users
Get a list of all of existing Directory Users matching the criteria specified.
/directory_users
One of
directory
orgroup
must be provided.
Unique identifier of the WorkOS Directory.
This value can be obtained from the WorkOS dashboard or from the WorkOS API.
Unique identifier of the WorkOS Directory Group.
This value can be obtained from the WorkOS API.
A cursor to use for pagination.
after
is a Directory User object ID that takes the formdirectory_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.A cursor to use for pagination.
before
is a Directory User object ID that takes the formdirectory_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.Upper limit on the number of Directory Users to return, between
1
and100
. The default value is10
.
An object containing Directory Users and metadata.
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
.Contains cursor options to utilize for pagination.
List Directory Users
1import WorkOS from '@workos-inc/node';23const workos = new WorkOS('sk_example_123456789');45const users = await workos.directorySync.listUsers({6 directory: 'directory_01ECAZ4NV9QMV47GW873HDCX74',7});
Response
1{2 "data": [{3 "id": "directory_user_01E1JJHG3BFJ3FNRRHSFWEBNCS",4 "idp_id": "1902",5 "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",6 "emails": [{7 "primary": true,8 "type": "work",10 }],11 "first_name": "Jan",12 "last_name": "Brown",14 "groups": [{15 "id": "directory_group_01E64QTDNS0EGJ0FMCVY9BWGZT",16 "name": "Engineering",17 "created_at": "2021-06-25T19:07:33.155Z",18 "updated_at": "2021-06-25T19:07:33.155Z",19 "raw_attributes": {...}20 }],21 "state": "active",22 "created_at": "2021-06-25T19:07:33.155Z",23 "updated_at": "2021-06-25T19:07:33.155Z",24 "custom_attributes": {25 "department": "Engineering"26 },27 "raw_attributes": {...}28 },29 {30 "id": "directory_user_01E1JJHG10ANRA2V6PAX3GD7TE",31 "idp_id": "8953",32 "emails": [{33 "primary": true,34 "type": "work",36 }],37 "first_name": "Rosalinda",38 "last_name": "Swift",40 "groups": [{41 "id": "directory_group_01E64QTDNS0EGJ0FMCVY9BWGZT",42 "name": "Engineering",43 "created_at": "2021-06-25T19:07:33.155Z",44 "updated_at": "2021-06-25T19:07:33.155Z",45 "raw_attributes": {...}46 }],47 "state": "active",48 "created_at": "2021-06-25T19:07:33.155Z",49 "updated_at": "2021-06-25T19:07:33.155Z",50 "custom_attributes": {51 "department": "Engineering"52 },53 "raw_attributes": {...}54 }],55 "object": "list",56 "list_metadata": {57 "after": "directory_user_01E4RH82CC8QAP8JTRCTNDSS4C",58 "before": "directory_user_01E4RH828021B9ZZB8KH8E2Z1W"59 }60}
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.
Unique identifier for the Directory Group.
Unique identifier for the group, assigned by the Directory Provider. Different Directory Providers use different ID formats.
The identifier of the Directory the Directory Group belongs to.
The name of the Directory Group.
An object containing the data returned from the Directory Provider.
Directory Group Object
{"created_at": "2021-06-25T19:07:33.155Z","updated_at": "2021-06-25T19:07:33.155Z",}
Get a Directory Group
Get the details of an existing Directory Group.
/directory_groups/:id
The unique identifier of the Directory Group.
Get a Directory Group
1import WorkOS from '@workos-inc/node';23const workos = new WorkOS('sk_example_123456789');45const group = await workos.directorySync.getGroup('directory_group_01E64QTDNS0EGJ0FMCVY9BWGZT');
Response
1{2 "id" : "directory_group_01E64QTDNS0EGJ0FMCVY9BWGZT",3 "idp_id": "02grqrue4294w24",4 "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",5 "name" : "Developers",6 "created_at": "2021-06-25T19:07:33.155Z",7 "updated_at": "2021-06-25T19:07:33.155Z",8 "raw_attributes": {...}9}
List Directory Groups
Get a list of all of existing directory users matching the criteria specified.
/directory_groups
One of
directory
oruser
must be provided.
Unique identifier of the WorkOS Directory.
This value can be obtained from the WorkOS dashboard or from the WorkOS API.
Unique identifier of the WorkOS Directory User.
This value can be obtained from the WorkOS API.
A cursor to use for pagination.
after
is a Directory Group object ID that takes the formdirectory_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.A cursor to use for pagination.
before
is a Directory Group object ID that takes the formdirectory_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.Upper limit on the number of Directory Groups to return, between
1
and100
. The default value is10
.
An object containing Directory Groups and metadata.
Array of Directory Groups in descending order by
created_at
timestamp.Contains cursor options to utilize for pagination.
List Directory Groups
1import WorkOS from '@workos-inc/node';23const workos = new WorkOS('sk_example_123456789');45const groups = await workos.directorySync.listGroups({6 directory: 'directory_01ECAZ4NV9QMV47GW873HDCX74',7});
Response
1{2 "id": "wh_34FKJ843CVE8F7BXQSPFH0M53V",3 "data" : [{4 "id" : "directory_group_01E1JJS84MFPPQ3G655FHTKX6Z",5 "idp_id": "02grqrue4294w24",6 "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",7 "name" : "Developers",8 "created_at": "2021-06-25T19:07:33.155Z",9 "updated_at": "2021-06-25T19:07:33.155Z",10 "raw_attributes": {...}11 }],12 "list_metadata" : {13 "after" : "directory_group_01E1JJS84MFPPQ3G655FHTKX6Z",14 "before" : "directory_group_01E1JJS84MFPPQ3G655FHTKX6Z"15 }16}
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
.
Unique identifier for the Audit Trail Event.
String representing the object's type. Currently the only possible value is
event
.Specific activity performed by the actor.
Unique identifier of the entity performing the action.
Display name of the entity performing the action.
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.Identifier for where the Event originated. This will be an IP address (IPv4 or IPv6), hostname, or device ID.
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.
ISO-8601 datetime at which the Event happened, with millisecond precision.
Unique identifier of the object or resource being acted upon.
Display name of the object or resource that is being acted upon.
Audit Trail Event Object
{"id": "evt_action_01DQX7EX39R54GXQ2NBBTSB608","object": "event_action","name": "user.login_succeeded"},"metadata": {"redirect": "/setup","description": "User login succeeded.","x_request_id": "ba7380eb-8cea-4b65-bbb1-4091e5bd76fc"},}
Publish an Audit Event
Create an Audit Event.
/events
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.
A single domain containing related members. This will normally be the domain of the Enterprise Client.
Specific activity performed by the actor.
The type of action performed. We recommend values that correspond to
Create
,Read
,Update
, andDelete
, however any string is accepted.Unique identifier of the entity performing the action.
Display name of the entity performing the action.
ISO-8601 datetime at which the Event happened, with millisecond precision.
Identifier for where the Event originated. This will be an IP address (IPv4 or IPv6), hostname, or device ID.
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.
Unique identifier of the object or resource being acted upon.
Display name of the object or resource that is being acted upon.
A boolean confirming the event was created.
Publish an Audit Event
1import WorkOS from '@workos-inc/node';23const workos = new WorkOS('sk_example_123456789');45const event = {6 action_type: 'r',7 action: 'user.login_succeeded',8 actor_id: 'user_01DEQWZNQT8Y47HDPSJKQS1J3F',9 actor_name: 'Annie Easley',10 group: 'foo-corp.com',11 location: '65.215.8.114',12 occurred_at: new Date(),13 target_id: 'user_01DEQWZNQT8Y47HDPSJKQS1J3F',15};1617workos.auditTrail.createEvent(event, { idempotency: '6d4c7400-d4bf-4623-a301-afe7b50569d3' });
Response
1{2 "success": true3}
List Audit Events
Get a list of all Audit Events matching the criteria specified.
/events
Array of specific activities performed by the actor to filter for.
Array of action types to filter for.
Array of unique identifiers to filter for. An Actor ID is a unique, machine-readable identifier for the entity performing the action.
Array of actor names to filter for. An Actor Name is a human-readable label for the entity performing the action.
A cursor to use for pagination.
after
is an Event object ID that takes the formevt_*
and defines your place in the paginated list of Event objects.after
will return all Events created after the cursor's value.A cursor to use for pagination.
before
is an Event object ID that takes the formevt_*
and defines your place in the paginated list of Event objects.before
will return all Events created before the cursor's value.