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 Developer Dashboard. There are two types of API keys:
- Deprecated Publishable keys are only meant to identify your account with WorkOS. They aren't secret, and can safely be made public in any of your client-side code. Publishable keys are prepended with
pk_*
. - Secret keys can perform any API request to WorkOS. They should be kept secure and private! Be sure to prevent secret keys from being made publicly accessible, such as in client-side code, GitHub, unsecured S3 buckets, and so forth. Secret keys are prepended with
sk_*
.
Each Environment in your account has both a publishable and secret key pair. API requests will be scoped to the provided key's Environment.
All API requests must be made over HTTPS. Any requests made over plain HTTP will fail.
API Key
{secretKey}
Set API Key
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
Successful request.
400The request was not acceptable, often indicates the parameters were not correct.
401The API key used was invalid.
403The API key used did not have the correct permissions.
404The resource was not found.
5xxIndicates an error with WorkOS' servers.
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.
Endpoint
Query Parameters
client_idstring
This value can be obtained from the SSO Configuration page in the WorkOS dashboard.
response_typestring
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.redirect_uristring
A Redirect URI to return an authorized user to.
domainstring (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 adomain
parameter into their authorization URL. Then, WorkOS will use thisdomain
value as a key to determine the connection and IdP to direct the user to for authentication.providerstring (optional)
Value used to authenticate all users with the same connection and Identity Provider.
Currently, the only supported value for
provider
isGoogleOAuth
. 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.statestring (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
connection_domain_invalid
There is no Connection for the provided domain.
connection_strategy_invalid
The Provider has multiple strategies associated per environment.
connection_unlinked
The Connection associated with the request is unlinked.
Get Authorization URL
1 2 3 4 5 6 7 8 9 10
import WorkOS from '@workos-inc/node'; const workos = new WorkOS('{secretKey}'); client.sso.getAuthorizationURL({ domain: '{foo-corp.com}', clientID: '{clientID}', redirectURI: 'https://your-app.com/callback', state: 'dj1kUXc0dzlXZ1hjUQ==', });
Response
https://api.workos.com/sso/authorize?
response_type=code&
client_id={projectID}&
redirect_uri=https://your-app.com/callback&
domain={foo-corp.com}&
state=dj1kUXc0dzlXZ1hjUQ==
Redirect URI
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
idstring
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.
objectstring
String representing the object's type. Currently the only possible value is
profile
.connection_typeenum
The type of SSO Connection used to authenticate the user.
- Possible values
ADFSSAML
AzureSAML
GenericOIDC
BETA
This is in beta, please contact us to request access.GenericSAML
GoogleOAuth
GoogleSAML
OktaSAML
OneLoginSAML
PingFederateSAML
PingOneSAML
SalesforceSAML
COMING SOON
VMwareSAML
emailstring
The user's email address.
first_namestring
The user's first name.
last_namestring
The user's last name.
idp_idstring
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_attributesobject
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
{
"{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": {{rawAttributes}}
}
Get a Profile
Get an access_token
along with the user's Profile using the code
we passed to your Redirect URI.
Endpoint
Query Parameters
client_idstring
This value can be obtained from the SSO Configuration page in the WorkOS dashboard.
client_secretstring
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_typestring
The method by which your application will receive an access token. This value should be
authorization_code
.codestring
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_tokenstring
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.
profileobject
The user Profile.
Get a Profile
1 2 3 4 5 6 7 8 9 10
import WorkOS from '@workos-inc/node'; const workos = new WorkOS('{secretKey}'); const profileOptions = { code, clientID: {clientID}, }; workos.sso.getProfile(profileOptions);
Response
{
"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": {{rawAttributes}}
}
}
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
idstring
Unique identifier for the Connection.
connection_typeenum
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
AzureSAML
GenericOIDC
BETA
This is in beta, please contact us to request access.GenericSAML
GoogleOAuth
GoogleSAML
OktaSAML
OneLoginSAML
PingFederateSAML
PingOneSAML
SalesforceSAML
COMING SOON
VMwareSAML
external_keystring
An additional Connection identifier used when constructing ACS URLs to integrate WorkOS with Identity Providers.
namestring
A human-readable name for the Connection. This will most commonly be the Enterprise Client's name.
oauth_redirect_uristring
An allowlisted callback URL for Connections that use OAuth (currently this value is only relevant for
GoogleOAuth
Connections). It indicates the location to return an authorized user to after both an authorization code is granted, and the authentication process is complete.oauth_secretstring
The client secret for Connections that use OAuth (currently this value is only relevant for
GoogleOAuth
Connections). It's a secret value known only to the application and authorization server.oauth_uidstring
The client ID for Connections that use OAuth (currently this value is only relevant for
GoogleOAuth
Connections). It's a public identifier for the application.objectstring
String representing the object's type. Currently the only possible value is
connection
.saml_entity_idstring
A unique name for an Identity Provider or Service Provider (i.e. application). Certain Connection types only require an IdP entity ID, whereas other Connection types will require both an IdP and SP entity ID.
saml_idp_urlstring
An endpoint provided by an Identity Provider that will initiate SAML authentication after receiving a SAML request from a Service Provider (i.e. application)
saml_relying_party_trust_certstring
Metadata file containing necessary information and certificates for a relying party (i.e. Service Provider or application). This metadata file provides a Microsoft AD FS instance with the information required to determine where it can expect to receive SAML assertions from. Only
ADFSSAML
Connections will use asaml_relying_party_trust_cert
.saml_x509_certsstring
Standardized certificate format for public-key data structures. This certificate is provided by the Identity Provider and used to verify the public key passed by the IdP in SAML assertions. This certificate allows a Service Provider (i.e. application) to verify that SAML assertions are made from an IdP that the SP trusts.
stateenum
Indicates whether a Connection is able to authenticate users.
- Possible values
draft
active
inactive
statusenumDeprecated
Indicates whether a Connection is able to communicate with an Identity Provider. Use state instead.
- Possible values
linked
unlinked
Connection Object
{
"{id}": "conn_01E4ZCR3C56J083X43JQXF3JK5",
"{connection_type}": "GoogleOAuth",
"{external_key}": "GbQX1B6LWUYcsGiq6k20iCUMA",
"{name}": "Foo Corp",
"{oauth_redirect_uri}": "http://{foo-corp.com}/sso/oauth/google/GbQX1B6LWUYcsGiq6k20iCUMA/callback",
"{oauth_secret}": "3gjDWvP3XGtS2hD4VMDwc-qh",
"{oauth_uid}": "453759831276-j0cue5069gf4l39u0idevk6ibk0clcli.apps.googleusercontent.com",
"{object}": "connection",
"organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
"{saml_entity_id}": null,
"{saml_idp_url}": null,
"{saml_relying_party_trust_cert}": null,
"{saml_x509_certs}": null,
"{state}": "active",
"{status}": "linked"
}
Get a Connection
Get the details of an existing connection.
Endpoint
Path Parameters
idstring
The unique identifier of the Connection.
Returns
A Connection.
Get a Connection
1 2 3 4 5
import WorkOS from '@workos-inc/node'; const workos = new WorkOS('{secretKey}'); const connection = await client.sso.getConnection('conn_01E4ZCR3C56J083X43JQXF3JK5');
Response
{
"connection_type": "GoogleOAuth",
"external_key": "GbQX1B6LWUYcsGiq6k20iCUMA",
"id": "conn_01E4ZCR3C56J083X43JQXF3JK5",
"name": "Foo Corp",
"oauth_redirect_uri": "http://{foo-corp.com}/sso/oauth/google/GbQX1B6LWUYcsGiq6k20iCUMA/callback",
"oauth_uid": "453759831276-j0cue5069gf4l39u0idevk6ibk0clcli.apps.googleusercontent.com",
"oauth_secret": "3gjDWvP3XGtS2hD4VMDwc-qh",
"object": "connection",
"organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
"saml_entity_id": null,
"saml_idp_url": null,
"saml_relying_party_trust_cert": null,
"saml_x509_certs": null,
"state": "active",
"status": "linked",
"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
Query Parameters
afterstring (optional)
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.beforestring (optional)
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.connection_typeenum (optional)
Filter Connections by their type.
- Possible values
ADFSSAML
AzureSAML
GenericOIDC
BETA
This is in beta, please contact us to request access.GenericSAML
GoogleOAuth
GoogleSAML
OktaSAML
OneLoginSAML
PingFederateSAML
PingOneSAML
SalesforceSAML
COMING SOON
VMwareSAML
domainstring (optional)
Filter Connections by their associated domain.
organization_idstring (optional)
Filter Connections by their associated organization.
limitinteger (optional)
Upper limit on the number of Connections to return, between
1
and100
. The default value is10
.
Returns
An object containing Connections and metadata.
dataarray of objects
An array of Connections in descending order by
created_at
timestamp.listMetadataobject
Contains cursor options to utilize for pagination.
List Connections
1 2 3 4 5
import WorkOS from '@workos-inc/node'; const workos = new WorkOS('{secretKey}'); const connections = await workos.sso.listConnections();
Response
{
"data": [
{
"connection_type": "GoogleOAuth",
"external_key": "GbQX1B6LWUYcsGiq6k20iCUMA",
"id": "conn_01E4ZCR3C56J083X43JQXF3JK5",
"name": "Foo Corp",
"oauth_redirect_uri": "http://{foo-corp.com}/sso/oauth/google/GbQX1B6LWUYcsGiq6k20iCUMA/callback",
"oauth_uid": "453759831276-j0cue5069gf4l39u0idevk6ibk0clcli.apps.googleusercontent.com",
"oauth_secret": "3gjDWvP3XGtS2hD4VMDwc-qh",
"object": "connection",
"organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
"saml_entity_id": null,
"saml_idp_url": null,
"saml_relying_party_trust_cert": null,
"saml_x509_certs": null,
"state": "active",
"status": "linked"
},
{
"connection_type": "OktaSAML",
"external_key": "GbQX1B6LWUYcsGiq6k20iCUMA",
"id": "conn_01E2NPPCT7XQ2MVVYDHWGK1WN4",
"name": "Example Co",
"oauth_redirect_uri": null,
"oauth_secret": null,
"oauth_uid": null,
"object": "connection",
"organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
"saml_entity_id": "http://www.okta.com/ert31rg83inANNuT04x7",
"saml_idp_url": "https://example-co.okta.com/app/exampleco-sso1337/ert31rg83inANNuT04x7/sso/saml",
"saml_relying_party_trust_cert": null,
"saml_x509_certs": [
"-----BEGIN CERTIFICATE-----
MIICVjCCAb8CAg37MA0GCSqGSIb3DQEBBQUAMIGbMQswCQYDVQQGEwJKUDEOMAwG
A1UECBMFVG9reW8xEDAOBgNVBAcTB0NodW8ta3UxETAPBgNVBAoTCEZyYW5rNERE
MRgwFgYDVQQLEw9XZWJDZXJ0IFN1cHBvcnQxGDAWBgNVBAMTD0ZyYW5rNEREIFdl
YiBDQTEjMCEGCSqGSIb3DQEJARYUc3VwcG9ydEBmcmFuazRkZC5jb20wHhcNMTIw
ODIyMDUyNzIzWhcNMTcwODIxMDUyNzIzWjBKMQswCQYDVQQGEwJKUDEOMAwGA1UE
CAwFVG9reW8xETAPBgNVBAoMCEZyYW5rNEREMRgwFgYDVQQDDA93d3cuZXhhbXBs
ZS5jb20wgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAMYBBrx5PlP0WNI/ZdzD
+6Pktmurn+F2kQYbtc7XQh8/LTBvCo+P6iZoLEmUA9e7EXLRxgU1CVqeAi7QcAn9
MwBlc8ksFJHB0rtf9pmf8Oza9E0Bynlq/4/Kb1x+d+AyhL7oK9tQwB24uHOueHi1
C/iVv8CSWKiYe6hzN1txYe8rAgMBAAEwDQYJKoZIhvcNAQEFBQADgYEAASPdjigJ
kXCqKWpnZ/Oc75EUcMi6HztaW8abUMlYXPIgkV2F7YanHOB7K4f7OOLjiz8DTPFf
jC9UeuErhaA/zzWi8ewMTFZW/WshOrm3fNvcMrMLKtH534JKvcdMg6qIdjTFINIr
evnAhf0cwULaebn+lMs8Pdl7y37+sfluVok=
-----END CERTIFICATE-----"
],
"state": "active",
"status": "linked"
}
],
"listMetadata": {
"before": "conn_01E2NPPCT7XQ2MVVYDHWGK1WN4",
"after": "conn_01EKKZXY1C4500PWY67PNQ3RGK",
}
}
Delete a Connection
Delete an existing connection.
Endpoint
Path Parameters
idstring
The unique identifier of the Connection.
Delete a Connection
1 2 3 4 5
import WorkOS from '@workos-inc/node'; const workos = new WorkOS('{secretKey}'); await client.sso.deleteConnection('conn_01E2NPPCT7XQ2MVVYDHWGK1WN4')
Endpoints
Passwordless Session
An object representing a passwordless authentication session.
Attributes
idstring
The unique ID of the session.
emailstring
The email address of the user for the session.
expires_atdate
The ISO-8601 datetime at which the session expires.
linkstring
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
.objectstring
String representing the object's type. Currently, the only possible value is
passwordless_session
.
Passwordless Session Object
{
"{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
Body Parameters
emailstring
The email of the user to authenticate.
typestring
The type of Passwordless Session to create. Currently, the only supported value is
MagicLink
.redirect_uristring (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.
statestring (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
Create a Passwordless Session
1 2 3 4 5 6 7 8 9 10
import WorkOS from '@workos-inc/node'; const workos = new WorkOS('{secretKey}'); const session_options = { email: '[email protected]{foo-corp.com}', type: 'MagicLink', }; const session = await workos.passwordless.createSession(session_options);
Response
{
"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
Path Parameters
idstring
The unique identifier of the Passwordless Session to send an email for.
Returns
A boolean
confirming the Magic Link was sent.
Email a Magic Link
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
{
"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
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
idstring
Unique identifier for the Directory.
domainstring
The URL associated with an Enterprise Client.
namestring
The name of the directory.
environment_idstring
A string representing the directory's environment id.
stateenum
Describes whether or not the Directory has been successfully connected to an external provider.
- Possible values
linked
unlinked
typeenum
The type of external Directory Provider integrated with.
- Possible values
azure scim v2.0
generic scim v1.1
generic scim v2.0
gusto
BETA
This is in beta, please contact us to request access.okta scim v1.1
okta scim v2.0
rippling
BETA
This is in beta, please contact us to request access.bamboohr
BETA
This is in beta, please contact us to request access.gsuite directory
workday
endpointstring
The endpoint a Directory Provider will make requests to.
bearer_tokenstring
The authentication token used when integrating WorkOS with Directory Providers.
Directory Object
{
"{id}": "directory_01ECAZ4NV9QMV47GW873HDCX74",
"{domain}": "{foo-corp.com}",
"{name}": "Foo Corp",
"{environment_id}": "environment_01EVEQ8GWZDERGY2MX47ZE2KAB",
"{state}": "unlinked",
"{type}": "gsuite directory",
"{endpoint}": "https://api.workos.com/scim/v2.0/UVKU1bQPEkCg8oim",
"{bearer_token}": "se_SNkwwRcnMkM02MeY6GUaibCIe",
}
List Directories
Get a list of all of your existing directories matching the criteria specified.
Endpoint
Query Parameters
domainstring (optional)
The domain of a Directory.
searchstring (optional)
Searchable text to match against Directory names.
afterstring (optional)
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.beforestring (optional)
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.limitinteger (optional)
Upper limit on the number of Connections to return, between
1
and100
. The default value is10
.
Returns
An object containing Directories.
dataarray of objects
Array of Directories in descending order by
created_at
timestamp.
List Directories
1 2 3 4 5
import WorkOS from '@workos-inc/node'; const workos = new WorkOS('{secretKey}'); const directories = await workos.directorySync.listDirectories();
Response
{
data: [{
"id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
"domain": "{foo-corp.com}",
"name": "Foo Corp",
"object": "directory",
"environment_id": "environment_01EVEQ8GWZDERGY2MX47ZE2KAB",
"state": "unlinked",
"type": "gsuite directory",
"endpoint": "https://api.workos.com/scim/v2.0/UVKU1bQPEkCg8oim",
"bearer_token": "se_SNkwwRcnMkM02MeY6GUaibCIe",
},
{
"id": "directory_01E8CS3GSBEBZ1F1CZAEE3KHDG",
"domain": "{foo-corp.com}",
"external_key": "r3NDlInUnAe6i4wG",
"name": "Foo Corp",
"object": "directory",
"environment_id": "environment_01EVEQ8GWZDERGY2MX47ZE2KAB",
"state": "linked",
"type": "okta scim v2.0",
"endpoint": "https://api.workos.com/scim/v2.0/yEGBYcUFpem4IEaC",
"bearer_token": "se_f8h7XDNlqooss6cEmUKYQCkS0"
}]
}
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
idstring
Unique identifier for the Directory User.
first_namestring
The first name of the user.
last_namestring
The last name of the user.
emailsarray of objects
The emails of the user.
usernamestring
The username of the user.
raw_attributesobject
An object containing the data returned from the Directory Provider.
Directory User Object
{
"{id}": "directory_user_01E1JG7J09H96KYP8HM9B0G5SJ",
"{first_name}": "Marcelina",
"{last_name}": "Davis",
"{emails}": [{
"primary": true,
"type": "work",
"value": "[email protected]{foo-corp.com}"
}],
"{username}": "[email protected]{foo-corp.com}",
"{raw_attributes}": {
"id": "directory_user_01E1JG7J09H96KYP8HM9B0G5SJ",
{rawAttributes}
}
}
Get a Directory User
Get the details of an existing Directory User.
Endpoint
Path Parameters
idstring
The unique identifier of the Directory User.
Returns
Get a Directory User
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
{
"id": "directory_user_01E1JG7J09H96KYP8HM9B0G5SJ",
"emails": [{
"primary": true,
"type": "work",
"value": "[email protected]{foo-corp.com}"
}],
"first_name": "Marcelina",
"last_name": "Davis",
"raw_attributes": {
"id": "directory_user_01E1JG7J09H96KYP8HM9B0G5SJ",
{rawAttributes}
},
"username": "[email protected]{foo-corp.com}"
}
List Directory Users
Get a list of all of existing Directory Users matching the criteria specified.
Endpoint
Query Parameters
One ofdirectory
orgroup
must be provided.
directorystring (optional)
Unique identifier of the WorkOS Directory.
This value can be obtained from the WorkOS dashboard or from the WorkOS API.
groupstring (optional)
Unique identifier of the WorkOS Directory Group.
This value can be obtained from the WorkOS API.
afterstring (optional)
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.beforestring (optional)
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.limitinteger (optional)
Upper limit on the number of Directory Users to return, between
1
and100
. The default value is10
.
Returns
An object containing Directory Users and metadata.
dataarray 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
.listMetadataobject
Contains cursor options to utilize for pagination.
List Directory Users
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
{
"data": [{
"id": "directory_user_01E1JJHG3BFJ3FNRRHSFWEBNCS",
"emails": [{
"primary": true,
"type": "work",
"value": "[email protected]{foo-corp.com}"
}],
"first_name": "Jan",
"last_name": "Brown",
"username": "[email protected]{foo-corp.com}",
"raw_attributes": {
"id": "directory_user_01E1JJHG3BFJ3FNRRHSFWEBNCS",
{rawAttributes}
},
},
{
"id": "directory_user_01E1JJHG10ANRA2V6PAX3GD7TE",
"emails": [{
"primary": true,
"type": "work",
"value": "[email protected]{foo-corp.com}"
}],
"first_name": "Rosalinda",
"last_name": "Swift",
"username": "[email protected]{foo-corp.com}",
"raw_attributes": {
"id": "directory_user_01E1JJHG10ANRA2V6PAX3GD7TE",
{rawAttributes}
},
],
"object": "list",
"listMetadata": {
"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
Directory Group Object
{
"{id}": "directory_group_01E1JJS84MFPPQ3G655FHTKX6Z",
"{name}": "Developers"
}
Get a Directory Group
Get the details of an existing Directory Group.
Endpoint
Path Parameters
idstring
The unique identifier of the Directory Group.
Returns
Get a Directory Group
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
{
"id" : "directory_group_01E64QTDNS0EGJ0FMCVY9BWGZT",
"name" : "Developers"
}
List Directory Groups
Get a list of all of existing directory users matching the criteria specified.
Endpoint
Query Parameters
One ofdirectory
oruser
must be provided.
directorystring (optional)
Unique identifier of the WorkOS Directory.
This value can be obtained from the WorkOS dashboard or from the WorkOS API.
userstring (optional)
Unique identifier of the WorkOS Directory User.
This value can be obtained from the WorkOS API.
afterstring (optional)
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.beforestring (optional)
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.limitinteger (optional)
Upper limit on the number of Directory Groups to return, between
1
and100
. The default value is10
.
Returns
An object containing Directory Groups and metadata.
dataarray of objects
Array of Directory Groups in descending order by
created_at
timestamp.listMetadataobject
Contains cursor options to utilize for pagination.
List Directory Groups
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
{
"data" : [{
"id" : "directory_group_01E1JJS84MFPPQ3G655FHTKX6Z",
"name" : "Developers"
}],
"listMetadata" : {
"after" : "directory_group_01E1JJS84MFPPQ3G655FHTKX6Z",
"before" : "directory_group_01E1JJS84MFPPQ3G655FHTKX6Z"
}
}
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
idstring
Unique identifier for the Audit Trail Event.
objectstring
String representing the object's type. Currently the only possible value is
event
.actionobject
Specific activity performed by the actor.
actor_idstring
Unique identifier of the entity performing the action.
actor_namestring
Display name of the entity performing the action.
groupstring
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.latitudestring
A geographic coordinate that specifies the north–south position.
longitudestring
A geographic coordinate that specifies the east–west position.
locationstring
Identifier for where the Event originated. This will be an IP address (IPv4 or IPv6), hostname, or device ID.
metadataobject (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_atdate
ISO-8601 datetime at which the Event happened, with millisecond precision.
target_idstring
Unique identifier of the object or resource being acted upon.
target_namestring
Display name of the object or resource that is being acted upon.
Audit Trail Event Object
{
"{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}",
"{latitude}": "40.676300",
"{longitude}": "-73.949200",
"{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
Headers
Idempotency-Keystring (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
groupstring
A single domain containing related members. This will normally be the domain of the Enterprise Client.
actionobject
Specific activity performed by the actor.
action_typestring
The type of action performed. We recommend values that correspond toCreate
,Read
,Update
, andDelete
, however any string is accepted.actor_idstring
Unique identifier of the entity performing the action.
actor_namestring
Display name of the entity performing the action.
occurred_atdate
ISO-8601 datetime at which the Event happened, with millisecond precision.
latitudestring
A geographic coordinate that specifies the north–south position.
longitudestring
A geographic coordinate that specifies the east–west position.
locationstring
Identifier for where the Event originated. This will be an IP address (IPv4 or IPv6), hostname, or device ID.
metadataobject (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_idstring
Unique identifier of the object or resource being acted upon.
target_namestring
Display name of the object or resource that is being acted upon.
Returns
A boolean confirming the event was created.
Publish an Audit Event
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
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}', latitude: '40.676300', longitude: '-73.949200', 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
{
"success": true
}
List Audit Events
Get a list of all Audit Events matching the criteria specified.
Endpoint
Query Parameters
actionarray of strings (optional)
Array of specific activities performed by the actor to filter for.
action_typearray of strings (optional)
Array of action types to filter for.
actor_idarray 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_namearray of strings (optional)
Array of actor names to filter for. An Actor Name is a human-readable label for the entity performing the action.
afterstring (optional)
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.beforestring (optional)
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.grouparray 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.
limitinteger (optional)
Upper limit on the number of Events to return, between
1
and100
. The default value is10
.occurred_atdate (optional)
ISO-8601 datetime to filter for when an Event occurred, with millisecond precision.
occurred_at_gtdate (optional)
ISO-8601 datetime to filter for when an Event occurred after, with millisecond precision.
occurred_at_gtedate (optional)
ISO-8601 datetime to filter for when an Event occurred at or after, with millisecond precision.
occurred_at_ltdate (optional)
ISO-8601 datetime to filter for when an Event occurred before, with millisecond precision.
occurred_at_ltedate (optional)
ISO-8601 datetime to filter for when an Event occurred at or before, with millisecond precision.
searchstring (optional)
Keyword string to filter for.
target_idarray 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_namearray 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.
dataarray of objects
Array of Audit Trail Events in descending order by
created_at
timestamp.listMetadataobject
Contains cursor options to utilize for pagination.
List Audit Events
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
import WorkOS from '@workos-inc/node'; const workos = new WorkOS('{secretKey}'); const options = { 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}"] } workos.auditTrail.listEvents(options);
Response
{
"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}",
"latitude": "40.676300",
"longitude": "-73.949200",
"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"
}],
"listMetadata": {
"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.activated
{
"data": {
"id": "conn_01EHWNC0FCBHZ3BJ7EGKYXK0E6",
"object": "connection",
"state": "active",
"status": "linked",
"saml_entity_id": null,
"connection_type": "OktaSAML",
"saml_idp_url": null,
"saml_x509_certs": [],
"name": "Foo Corp's Connection",
"organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
"saml_relying_party_private_key": null,
"saml_relying_party_public_key": null,
"oauth_uid": null,
"oauth_secret": null,
"oauth_redirect_uri": null,
"oidc_client_id": null,
"oidc_client_secret": null,
"oidc_discovery_endpoint": null,
"oidc_redirect_uri": null,
"domains": [
{
"id": "conn_domain_01EHWNFTAFCF3CQAE5A9Q0P1YB",
"object": "connection_domain",
"domain": "{foo-corp.com}"
}
]
},
"event": "connection.activated"
}
connection.deactivated
{
"data": {
"id": "conn_01EHWNC0FCBHZ3BJ7EGKYXK0E6",
"object": "connection",
"state": "inactive",
"status": "unlinked",
"saml_entity_id": null,
"connection_type": "OktaSAML",
"saml_idp_url": null,
"saml_x509_certs": [],
"name": "Foo Corp's Connection",
"organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
"saml_relying_party_private_key": null,
"saml_relying_party_public_key": null,
"oauth_uid": null,
"oauth_secret": null,
"oauth_redirect_uri": null,
"oidc_client_id": null,
"oidc_client_secret": null,
"oidc_discovery_endpoint": null,
"oidc_redirect_uri": null,
"domains": [
{
"id": "conn_domain_01EHWNFTAFCF3CQAE5A9Q0P1YB",
"object": "connection_domain",
"domain": "{foo-corp.com}"
}
]
},
"event": "connection.deactivated"
}
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
Directory User Webhooks
{
"data": {
"id": "directory_user_01E1X1B89NH8Z3SDFJR4H7RGX7",
"directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
"emails": [{
"primary": true,
"type": "work",
"value": "[email protected]{foo-corp.com}"
}],
"first_name": "Lela",
"last_name": "Block",
"username": "[email protected]{foo-corp.com}"
},
"event": "dsync.user.created"
}
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.
dsync.group.created
{
"data": {
"id": "directory_group_01E1X5GPMMXF4T1DCERMVEEPVW",
"directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
"name": "Developers",
"users": [{
"id": "directory_user_01E1X2NKBWA5YDYF23Q7G45YGA",
"emails": [{
"primary": true,
"type": "work",
"value": "[email protected]{foo-corp.com}"
}],
"first_name": "Kiana",
"last_name": "Flatley",
"username": "[email protected]{foo-corp.com}"
},
{
"id": "directory_user_01E1X1B89NH8Z3SDFJR4H7RGX7",
"emails": [{
"primary": true,
"type": "work",
"value": "[email protected]{foo-corp.com}"
}],
"first_name": "Veda",
"last_name": "Block",
"username": "[email protected]{foo-corp.com}"
}
]
},
"event": "dsync.group.created"
}
dsync.group.updated
{
"data": {
"id": "directory_group_01E1X1B89NH8Z3SDFJR4H7RGX7",
"directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
"name": "Developers"
},
"event": "dsync.group.updated"
}
dsync.group.user_added
{
"data": {
"directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
"user": {
"id": "directory_user_01E1X56GH84T3FB41SD6PZGDBX",
"emails": [{
"primary": true,
"type": "work",
"value": "[email protected]{foo-corp.com}"
}],
"first_name": "Eric",
"last_name": "Schneider",
"username": "[email protected]{foo-corp.com}"
},
"group": {
"id": "directory_group_01E1X5GPMMXF4T1DCERMVEEPVW",
"name": "Developers"
}
},
"event": "dsync.group.user_added",
}
dsync.group.user_removed
{
"event": "dsync.group.user_removed",
"data": {
"directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
"user": {
"id": "directory_user_01E1X56GH84T3FB41SD6PZGDBX",
"emails": [{
"primary": true,
"type": "work",
"value": "[email protected]{foo-corp.com}"
}],
"first_name": "Eric",
"last_name": "Schneider",
"username": "[email protected]{foo-corp.com}"
},
"group": {
"id": "directory_group_01E1X5GPMMXF4T1DCERMVEEPVW",
"name": "Developers"
}
}
}
dsync.group.deleted
{
"data": {
"id": "directory_group_01E1X5GPMMXF4T1DCERMVEEPVW",
"directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
"name": "Developers"
},
"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 that are scoped to their Organization.
Endpoints
Organization
An Organization describes users which share a common domain or domains.
Each Connection, Directory, and Audit Trail Event belong to an Organization. This relationship is implicitly described by the resource's domain.
Attributes
idstring
Unique identifier for the Organization.
namestring
The name of the Organization.
domainsarray of objects
List of Organization Domains.
Organization Object
{
"{id}": "org_01EHZNVPK3SFK441A1RGBFSHRT",
"object": "organization",
"{name}": "Foo Corp",
"{domains}": [
{
"id": "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A",
"object": "organization_domain",
"domain": "{foo-corp.com}"
},
]
}
List Organizations
Get a list of all of your existing organizations matching the criteria specified.
Endpoint
Query Parameters
domainsarray of strings (optional)
The domains of an Organization. Any Organization with a matching domain will be returned.
afterstring (optional)
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.beforestring (optional)
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.limitinteger (optional)
Upper limit on the number of Organizations to return, between
1
and100
. The default value is10
.
Returns
An object containing Organizations.
dataarray of objects
Array of Organizations in descending order by
created_at
timestamp.listMetadataobject
Contains cursor options to utilize for pagination.
List Organizations
1 2 3 4 5 6 7
import WorkOS from '@workos-inc/node'; const workos = new WorkOS('{secretKey}'); const organizations = await workos.portal.listOrganizations({ domains: ['{foo-corp.com}'] });
Response
{
"data": [
{
"id": "org_01EHZNVPK3SFK441A1RGBFSHRT",
"object": "organization",
"name": "Foo Corp",
"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"
}
]
}
],
"listMetadata": {
"before": "org_01EHZNVPK3SFK441A1RGBFSHRT",
"after": "org_01EJBGJT2PC6638TN5Y380M40Z",
}
}
Create an Organization
Create an Organization with a set of domains.
Endpoint
Body Parameters
Returns
An Organization object.
Create an Organization
1 2 3 4 5 6 7 8
import WorkOS from '@workos-inc/node'; const workos = new WorkOS('{secretKey}'); const organization = await workos.portal.createOrganization({ name: 'Foo Corp', domains: ['{foo-corp.com}'] });
Response
{
"id": "org_01EHZNVPK3SFK441A1RGBFSHRT",
"object": "organization",
"name": "Foo Corp",
"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
Body Parameters
Returns
An Organization object.
Update an Organization
1
// SDK support coming soon
Response
{
"id": "org_01EHZNVPK3SFK441A1RGBFSHRT",
"object": "organization",
"name": "Foo Corporation",
"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"
}
]
}
Organization Domain Object
{
"{id}": "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A",
"object": "organization_domain",
"{domain}": "{foo-corp.com}"
}
Generate a Portal Link
Generate a Portal Link scoped to an Organization.
Endpoint
Body Parameters
organizationstring
An Organization identifier.
intentenum
The intent of the Admin Portal.
- Possible values
sso
return_urlstring (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
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: GeneratePortalLinkIntent.SSO, returnUrl: "https://www.example.com" //optional });
Response
{
"link": "https://id.workos.com/portal/launch?secret=JteZqfJZqUcgWGaYCC6iI0gW0",
}