The WorkOS API enables adding Enterprise Ready features to your application. This REST API provides programmatic access to User Management, Single Sign-On, Directory Sync, and Audit Log resources.
Sign in to see code examples customized with your API keys and data.
https://api.workos.com
WorkOS offers native SDKs in several popular programming languages. Choose one language below to see our API Reference in your application’s language.
Don't see an SDK you need? Contact us to request an SDK!
You can test the API directly with cURL, or use the Postman collection for convenience.
Check out the guide about the WorkOS API Postman collection to learn more about it.
WorkOS authenticates your API requests using your account’s API keys. API requests made without authentication or using an incorrect key will return a 401
error. Requests using a valid key but with insufficient permissions will return a 403
error. All API requests must be made over HTTPS. Any requests made over plain HTTP will fail.
curl https://api.workos.com/directories \ --header "Authorization: Bearer sk_example_123456789"
You can view and manage your API keys in the WorkOS Dashboard.
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.
WorkOS uses standard HTTP response codes to indicate the success or failure of your API requests.
200
400
401
403
404
422
429
5xx
Many top-level resources have support for bulk fetches via list API methods. For instance, you can list connections, list directory users, and list directory groups. These list API methods share a common structure, taking at least these four parameters: limit
, order
, after
, and before
.
WorkOS utilizes pagination via the after
and before
parameters. Both parameters take an existing object ID value and return objects in either descending or ascending order by creation time.
curl https://api.workos.com/connections?limit=100 \ --header "Authorization: Bearer sk_example_123456789"
{ "data": [ { "object": "connection", "id": "conn_01E4ZCR3C56J083X43JQXF3JK5", "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY", "connection_type": "GoogleOAuth", "name": "Foo Corp", "state": "active", "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:08:33.155Z" }, { "object": "connection", "id": "conn_01E2NPPCT7XQ2MVVYDHWGK1WN4", "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY", "connection_type": "OktaSAML", "name": "Example Co", "state": "active", "created_at": "2021-06-25T19:09:33.155Z", "updated_at": "2021-06-25T19:10:33.155Z" } ], "list_metadata": { "before": "conn_01E2NPPCT7XQ2MVVYDHWGK1WN4", "after": null } }
Parameters
An object ID that defines your place in the list. When the ID is not present, you are at the end of the list.
For example, if you make a list request and receive 100 objects, ending with "obj_123"
, your subsequent call can include before="obj_123"
to fetch a new batch of objects before "obj_123"
.
An object ID that defines your place in the list. When the ID is not present, you are at the end of the list.
For example, if you make a list request and receive 100 objects, ending with "obj_123"
, your subsequent call can include after="obj_123"
to fetch a new batch of objects after "obj_123"
.
Upper limit on the number of objects to return, between 1
and 100
. The default value is 10
.
Order the results by the creation time. Supported values are "asc"
and "desc"
for showing older and newer records first respectively. Default order is descending.
The WorkOS API supports idempotency which guarantees that performing the same operation multiple times will have the same result as if the operation were performed only once. This is handy in situations where you may need to retry a request due to a failure or prevent accidental duplicate requests from creating more than one resource.
To achieve idempotency, you can add Idempotency-Key
request header to any WorkOS API request with a unique string as the value. Each subsequent request matching this unique string will return the same response. We suggest using v4 UUIDs for idempotency keys to avoid collisions.
curl --request POST \ --url https://api.workos.com/organizations \ -H "Authorization: Bearer sk_example_123456789" \ -H "Idempotency-Key: cd320c5c-e928-4212-a5bd-986c29362867" \ -d 'name="Foo Corp"' \ -d 'domains[]="foo-corp.com"'
Idempotency keys expire after 24 hours. The WorkOS API will generate a new response if you submit a request with an expired key.
WorkOS APIs are rate limited to ensure that they are fast for everyone. If you find yourself getting 429 errors, double check your integration to make sure you aren’t making unnecessary requests.
Name | Path | Limit |
---|---|---|
All requests | * | 6,000 requests per 60 seconds per IP address |
This rate limits applies to all environments, staging and production. Exceptions to the general rate limit are listed below.
Name | Path | Limit |
---|---|---|
Get Authorization URL | /sso/authorize | 1,000 requests per 60 seconds per connection |
Name | Path | Limit |
---|---|---|
Directory Users | /directory_users | 4 requests per second per directory |
Rate limiting for User Management APIs are enforced on an account basis.
Name | Path | Limit |
---|---|---|
Reads | /user_management/* | 1,000 requests per 10 seconds |
Writes | /user_management/* | 500 requests per 10 seconds |
Authentication | /user_management/authenticate | 10 requests per 60 seconds per email or challenge ID |
Magic Auth | /user_management/magic_auth/send | 3 requests per 60 seconds per email |
Email verification | /user_management/:id/email_verification/send | 3 requests per 60 seconds per user |
Password reset | /user_management/password_reset/send | 3 requests per 60 seconds per email |
Name | Limits |
---|---|
Reads | 1,000 requests per 10 seconds |
Writes | 500 requests per 10 seconds |
Sign-ins | 3 requests per 60 seconds per IP address |
Email sign-ins | 10 requests per 60 seconds per email and IP address |
Magic Auth sign-ins | 10 requests per 60 seconds per IP address and challenge ID |
Magic Auth code requests | 3 requests per 60 seconds per IP address and email |
Events represent activity that has occurred within WorkOS or within third-party identity and directory providers. They are used to keep your app in sync with WorkOS data. For more details on consuming events in your app, check out the data syncing guide.
Refer to the Events page for a full list of events that WorkOS emits.
Get a list of all of events up to 30 days old.
curl --request GET --url "https://api.workos.com/events" \ --header "Authorization: Bearer sk_example_123456789"
{ "object": "list", "data": [ { "object": "event", "id": "event_01H2GNQD5D7ZE06FDDS75NFPHY", "event": "dsync.group.user_added", "data": { "user": { "id": "directory_user_01E1X56GH84T3FB41SD6PZGDBX", "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74", "organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y", "idp_id": "2936", "emails": [ { "primary": true, "type": "work", "value": "eric@example.com" } ], "first_name": "Eric", "last_name": "Schneider", "job_title": "Software Engineer", "username": "eric@example.com", "state": "active", "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z", "custom_attributes": { "department": "Engineering" }, "raw_attributes": {} }, "group": { "id": "directory_group_01E1X5GPMMXF4T1DCERMVEEPVW", "idp_id": "02grqrue4294w24", "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74", "organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y", "name": "Developers", "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z", "raw_attributes": {} } }, "created_at": "2023-06-09T18:12:01.837Z" } ], "list_metadata": { "after": "event_01H2GQNMQNH8VRXVR7AEYG9XCJ" } }
GET
/events
Parameters
Filter to only return events of particular types.
Filter to only return events belonging only to specific Organizations. User events (e.g user.created) will not be Organization specific.
Maximum number of records to return. Accepts values between 1
and 100
. Default is 10
.
Date range start for a stream of events. Mutually exclusive with the after
parameter.
Date range end for a stream of events.
Pagination cursor to receive records after a provided event ID. Mutually exclusive with the range_start
parameter.
Returns
object
List of the corresponding event objects.
An object ID that defines your place in the list. When the ID is not present, you are at the end of the list.
For example, if you make a list request and receive 100 objects, ending with "obj_123"
, your subsequent call can include before="obj_123"
to fetch a new batch of objects before "obj_123"
.
An object ID that defines your place in the list. When the ID is not present, you are at the end of the list.
For example, if you make a list request and receive 100 objects, ending with "obj_123"
, your subsequent call can include after="obj_123"
to fetch a new batch of objects after "obj_123"
.
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.
{ "object": "organization", "id": "org_01EHZNVPK3SFK441A1RGBFSHRT", "name": "Foo Corp", "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z", "domains": [ { "id": "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A", "object": "organization_domain", "domain": "foo-corp.com" } ] }
organization
Distinguishes the Organization object.
Unique identifier of the Organization.
A descriptive name for the Organization. This field does not need to be unique.
The timestamp when the Organization was last created.
The timestamp when the Organization was last updated.
List of Organization Domains.
Get the details of an existing organization.
curl https://api.workos.com/organizations/org_01EHZNVPK3SFK441A1RGBFSHRT \ --header "Authorization: Bearer sk_example_123456789"
{ "id": "org_01EHZNVPK3SFK441A1RGBFSHRT", "object": "organization", "name": "Foo Corporation", "allow_profiles_outside_organization": false, "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z", "domains": [ { "domain": "foo-corp.com", "id": "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A", "object": "organization_domain" }, { "domain": "another-foo-corp-domain.com", "id": "org_domain_01EHZNS0H9W90A90FV79GAB6AB", "object": "organization_domain" } ] }
Get a list of all of your existing organizations matching the criteria specified.
curl https://api.workos.com/organizations?domains=foo-corp.com \ --header "Authorization: Bearer sk_example_123456789"
{ "data": [ { "id": "org_01EHZNVPK3SFK441A1RGBFSHRT", "object": "organization", "name": "Foo Corp", "allow_profiles_outside_organization": false, "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z", "domains": [ { "domain": "foo-corp.com", "id": "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A", "object": "organization_domain" }, { "domain": "another-foo-corp-domain.com", "id": "org_domain_01EHZNS0H9W90A90FV79GAB6AB", "object": "organization_domain" } ] } ], "list_metadata": { "before": "org_01EHZNVPK3SFK441A1RGBFSHRT", "after": "org_01EJBGJT2PC6638TN5Y380M40Z" } }
GET
/organizations
Parameters
The domains of an Organization. Any Organization with a matching domain will be returned.
Upper limit on the number of objects to return, between 1
and 100
. The default value is 10
.
An object ID that defines your place in the list. When the ID is not present, you are at the end of the list.
For example, if you make a list request and receive 100 objects, ending with "obj_123"
, your subsequent call can include before="obj_123"
to fetch a new batch of objects before "obj_123"
.
An object ID that defines your place in the list. When the ID is not present, you are at the end of the list.
For example, if you make a list request and receive 100 objects, ending with "obj_123"
, your subsequent call can include after="obj_123"
to fetch a new batch of objects after "obj_123"
.
Order the results by the creation time. Supported values are "asc"
and "desc"
for showing older and newer records first respectively. Default order is descending.
Returns
object
Array of Organizations ordered by creation time.
An object ID that defines your place in the list. When the ID is not present, you are at the end of the list.
For example, if you make a list request and receive 100 objects, ending with "obj_123"
, your subsequent call can include before="obj_123"
to fetch a new batch of objects before "obj_123"
.
An object ID that defines your place in the list. When the ID is not present, you are at the end of the list.
For example, if you make a list request and receive 100 objects, ending with "obj_123"
, your subsequent call can include after="obj_123"
to fetch a new batch of objects after "obj_123"
.
Creates a new organization in the current environment.
curl --request POST \ --url https://api.workos.com/organizations \ --header "Authorization: Bearer sk_example_123456789" \ --header "Content-Type: application/json" \ -d @- <<BODY { "name": "Foo Corp", "domain_data": [ { "domain": "foo-corp.com", "state": "pending" } ] } BODY
{ "id": "org_01EHZNVPK3SFK441A1RGBFSHRT", "object": "organization", "name": "Foo Corp", "allow_profiles_outside_organization": false, "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z", "domains": [ { "domain": "foo-corp.com", "id": "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A", "object": "organization_domain" }, { "domain": "another-foo-corp-domain.com", "id": "org_domain_01EHZNS0H9W90A90FV79GAB6AB", "object": "organization_domain" } ] }
POST
/organizations
Parameters
A descriptive name for the Organization. This field does not need to be unique.
The domain to be added to the organization.
The verification state of the domain.
Use the "verified"
state to indicate that the organization has confirmed
to you that they own this domain. Verified domains must be unique within
a WorkOS environment and may belong only to a single organization.
Use the "pending"
state to indicate that the organization hasn’t verified
ownership of the domain. You can use Domain Verification
to allow an organization admin to verify the domain via Admin Portal.
Returns
Updates an organization in the current environment.
curl --request PUT \ --url https://api.workos.com/organizations/org_01EHZNVPK3SFK441A1RGBFSHRT \ --header "Authorization: Bearer sk_example_123456789" \ --header "Content-Type: application/json" \ -d @- <<BODY { "name": "Foo Corp", "domain_data": [ { "domain": "foo-corp.com", "state": "verified" } ] } BODY
{ "id": "org_01EHZNVPK3SFK441A1RGBFSHRT", "object": "organization", "name": "Foo Corp", "allow_profiles_outside_organization": false, "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z", "domains": [ { "domain": "foo-corp.com", "id": "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A", "object": "organization_domain" }, { "domain": "another-foo-corp-domain.com", "id": "org_domain_01EHZNS0H9W90A90FV79GAB6AB", "object": "organization_domain" } ] }
PUT
/organizations /:id
Parameters
A descriptive name for the Organization. This field does not need to be unique.
The domain to be added to the organization.
The verification state of the domain.
Use the "verified"
state to indicate that the organization has confirmed
to you that they own this domain. Verified domains must be unique within
a WorkOS environment and may belong only to a single organization.
Use the "pending"
state to indicate that the organization hasn’t verified
ownership of the domain. You can use Domain Verification
to allow an organization admin to verify the domain via Admin Portal.
Returns
Deletes an organization in the current environment.
curl --request DELETE \ --url https://api.workos.com/organizations/org_01EHZNVPK3SFK441A1RGBFSHRT \ --header "Authorization: Bearer sk_example_123456789"
DELETE
/organizations /:id
Parameters
Unique identifier of the Organization.
An Organization Domain (also known as a User Email Domain) represents an Organization's domain.
These domains restrict which email addresses are able to sign in through SAML Connections when allow_profiles_outside_organization is false
. This is the default behavior for Organizations. See here for more details on this behavior.
{ "id": "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A", "object": "organization_domain", "domain": "foo-corp.com" }
organization_domain
Distinguishes the Organization Domain object.
Unique identifier for the Organization Domain.
Domain for the Organization Domain.
A set of user authentication and organization security features designed to provide a fast, scalable integration while handling all of the user management complexity that comes with advanced business and customer needs.
To automatically respond to User Management activities, like authentication and changes related to the users, use the corresponding events.
Represents a user identity in your application. A user can sign up in your application directly with a method like password, or they can be JIT-provisioned through an organization’s SSO connection.
Users may belong to organizations as members.
See the events reference documentation for the user events.
{ "object": "user", "id": "user_01E4ZCR3C56J083X43JQXF3JK5", "email": "marcelina.davis@example.com", "first_name": "Marcelina", "last_name": "Davis", "email_verified": true, "profile_picture_url": "https://workoscdn.com/images/v1/123abc", "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z" }
user
Distinguishes the user object.
The unique ID of the user.
The email address of the user.
The first name of the user.
The last name of the user.
Whether the user’s email has been verified.
A URL reference to an image representing the user.
Currently, this URL will be present for users who have a profile picture from a linked Google or GitHub OAuth identity. New image sources may be added in the future.
The timestamp when the user was created.
The timestamp when the user was last updated.
Get the details of an existing user.
curl https://api.workos.com/user_management/users/user_01E4ZCR3C56J083X43JQXF3JK5 \ --header "Authorization: Bearer sk_example_123456789"
{ "object": "user", "id": "user_01E4ZCR3C56J083X43JQXF3JK5", "email": "marcelina.davis@example.com", "first_name": "Marcelina", "last_name": "Davis", "email_verified": true, "profile_picture_url": "https://workoscdn.com/images/v1/123abc", "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z" }
Get a list of all of your existing users matching the criteria specified.
curl https://api.workos.com/user_management/users \ --header "Authorization: Bearer sk_example_123456789"
{ "data": [ { "object": "user", "id": "user_01E4ZCR3C56J083X43JQXF3JK5", "email": "marcelina.davis@example.com", "first_name": "Marcelina", "last_name": "Davis", "email_verified": true, "profile_picture_url": "https://workoscdn.com/images/v1/123abc", "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z" } ], "list_metadata": { "before": "user_01E4ZCR3C56J083X43JQXF3JK5", "after": "user_01EJBGJT2PC6638TN5Y380M40Z" } }
GET
/user_management /users
Parameters
Filter users by their email.
Filter users by the organization they are members of.
Upper limit on the number of objects to return, between 1
and 100
. The default value is 10
.
An object ID that defines your place in the list. When the ID is not present, you are at the end of the list.
For example, if you make a list request and receive 100 objects, ending with "obj_123"
, your subsequent call can include before="obj_123"
to fetch a new batch of objects before "obj_123"
.
An object ID that defines your place in the list. When the ID is not present, you are at the end of the list.
For example, if you make a list request and receive 100 objects, ending with "obj_123"
, your subsequent call can include after="obj_123"
to fetch a new batch of objects after "obj_123"
.
Order the results by the creation time. Supported values are "asc"
and "desc"
for showing older and newer records first respectively. Default order is descending.
Returns
object
Array of users ordered by creation time.
An object ID that defines your place in the list. When the ID is not present, you are at the end of the list.
For example, if you make a list request and receive 100 objects, ending with "obj_123"
, your subsequent call can include before="obj_123"
to fetch a new batch of objects before "obj_123"
.
An object ID that defines your place in the list. When the ID is not present, you are at the end of the list.
For example, if you make a list request and receive 100 objects, ending with "obj_123"
, your subsequent call can include after="obj_123"
to fetch a new batch of objects after "obj_123"
.
Create a new user in the current environment.
curl --request POST \ --url https://api.workos.com/user_management/users \ --header "Authorization: Bearer sk_example_123456789" \ --header "Content-Type: application/json" \ -d @- <<BODY { "email": "marcelina@example.com", "password": "i8uv6g34kd490s", "first_name": "Marcelina", "last_name": "Davis", "email_verified": false } BODY
{ "object": "user", "id": "user_01E4ZCR3C56J083X43JQXF3JK5", "email": "marcelina.davis@example.com", "first_name": "Marcelina", "last_name": "Davis", "email_verified": true, "profile_picture_url": "https://workoscdn.com/images/v1/123abc", "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z" }
POST
/user_management /users
Parameters
The email address of the user.
The password to set for the user.
The hashed password to set for the user. Mutually exclusive with password
.
The algorithm originally used to hash the password, used when providing a password_hash
. Valid values are bcrypt
, firebase-scrypt
, and ssha
.
See the Firebase Migration guide for an example of how to format the password_hash
when importing firebase-scrypt
passwords.
The first name of the user.
The last name of the user.
Whether the user’s email address was previously verified.
You should normally use the email verification flow
to verify a user’s email address. However, if the user’s email was previously verified, or
is being migrated from an existing user store, this can be set to true
to mark it as
already verified.
Returns
Updates properties of a user. The omitted properties will be left unchanged.
curl --request PUT \ --url https://api.workos.com/user_management/users/user_01EHQ7ZGZ2CZVQJGZ5ZJZ1ZJGZ \ --header "Authorization: Bearer sk_example_123456789" \ --header "Content-Type: application/json" \ -d @- <<BODY { "first_name": "Marcelina", "last_name": "Davis", "email_verified": true } BODY
{ "object": "user", "id": "user_01E4ZCR3C56J083X43JQXF3JK5", "email": "marcelina.davis@example.com", "first_name": "Marcelina", "last_name": "Davis", "email_verified": true, "profile_picture_url": "https://workoscdn.com/images/v1/123abc", "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z" }
PUT
/user_management /users /:id
Parameters
The unique ID of the user.
The user’s first name.
The user’s last name.
Whether the user’s email address was previously verified.
You should normally use the email verification flow
to verify a user’s email address. However, if the user’s email was previously verified, or
is being migrated from an existing user store, this can be set to true
to mark it as
already verified.
The password to set for the user.
The hashed password to set for the user. Mutually exclusive with password
.
The algorithm originally used to hash the password, used when providing a password_hash
. Valid values are bcrypt
, firebase-scrypt
, and ssha
.
See the Firebase Migration guide for an example of how to format the password_hash
when importing firebase-scrypt
passwords.
Returns
Deletes a user in the current environment.
curl --request DELETE \ --url https://api.workos.com/user_management/users/user_01F3GZ5ZGZBZVQGZVHJFVXZJGZ \ --header "Authorization: Bearer sk_example_123456789"
DELETE
/user_management /users /:id
Parameters
The unique ID of the user.
Generates an OAuth 2.0 authorization URL to authenticate a user with AuthKit or SSO.
curl https://api.workos.com/user_management/authorize -G \ -d response_type=code \ -d client_id=client_123456789 \ -d redirect_uri=https://your-app.com/callback \ -d state=dj1kUXc0dzlXZ1hjUQ== \ -d connection_id=conn_01E4ZCR3C56J083X43JQXF3JK5
https://api.workos.com/user_management/authorize? response_type=code& client_id=client_123456789& redirect_uri=https://your-app.com/callback& state=dj1kUXc0dzlXZ1hjUQ==& connection_id=conn_01E4ZCR3C56J083X43JQXF3JK5
GET
/user_management /authorize
The only valid option for the response type parameter is "code"
.
The "code"
parameter value initiates an authorization code grant type. This grant type allows you to exchange an authorization code for an access token during the redirect that takes place after a user has authenticated with an identity provider.
Identifies the application making the request to the WorkOS server. You can obtain your client ID from the API Keys page in the dashboard.
Code challenge is derived from the code verifier used for the PKCE flow.
The only valid PKCE code challenge method is "S256"
.
This parameter is required when specifying a code_challenge
for the PKCE flow.
Where to redirect the user after they complete the authentication process. You must use one of the redirect URIs configured via the Redirects page on the dashboard.
Used to initiate SSO for a connection. The value should be a WorkOS connection ID.
You 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.
Used to initiate SSO for an organization. The value should be a WorkOS organization ID.
You can persist the WorkOS organization ID with application user or team identifiers. WorkOS will use the organization ID to determine the appropriate connection and the IdP to direct the user to for authentication.
Used to initiate authentication with AuthKit, Google OAuth, Microsoft OAuth, or GitHub OAuth.
An optional parameter that can be used to encode arbitrary information to help restore application state between redirects. If included, the redirect URI received from WorkOS will contain the exact state value that was passed.
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 supported for OAuth, OpenID Connect, Okta, and Entra ID connections.
Can be used to pre-fill the domain field when initiating authentication with Microsoft OAuth or with a Google SAML connection type.
Specify which AuthKit screen users should land on upon redirection (Only applicable when provider is 'authkit').
Returns
An OAuth 2.0 authorization URL.
If you are using AuthKit, set the provider parameter to "authkit"
, which will generate an authorization URL for your AuthKit domain. AuthKit will take care of detecting the user’s authentication method, such as identifying whether they use Email + Password or Single Sign-On,and direct them to the corresponding login flow.
Otherwise, to generate an authorization URL for a WorkOS SSO connection, you’ll have to specify the user’s connection, organization, or OAuth provider as a parameter. These connection selectors are mutually exclusive, and exactly one must be provided. The generated URL automatically directs the 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 sign-in flow.
In the OAuth 2.0 protocol, a redirect URI is the location that the user is redirected to once they have successfully authenticated with their identity provider.
When redirecting the user, WorkOS will generate an authorization code and pass it to your redirect URI as a code
query parameter, your app will use this code to authenticate the user. Additionally, WorkOS can pass a state
parameter back to your application that you may use to encode arbitrary information to restore your application state between the redirects.
https://your-app.com/callback?code=01E2RJ4C05B52KKZ8FSRDAP23J&state=dj1kUXc0dzlXZ1hjUQ==
You’ll need to configure the allowed redirect URIs for your application via the Redirects page in the dashboard. Without a valid redirect URI, your users will be unable to sign in. Make sure that the redirect URI you use as a parameter to get the authorization URL matches one of the redirect URIs you have configured in the dashboard.
Redirect URIs follow stricter requirements in production environments:
HTTPS
protocol is required in production environmentsHTTP
and localhost
are allowed in staging environmentsThe Proof Key for Code Exchange (PKCE) flow is an extension to the OAuth 2.0 Authorization Code flow. It enables public clients, like native apps or single-page apps, to perform the authorization code flow securely. If you are developing a client that makes API calls in public, you’ll need to use this flow.
In this flow, your client generates a code verifier which is a high-entropy cryptographic random string. A code challenge is derived by hashing the code verifier. Instead of using a client secret, provide the code challenge when getting the authorization URL and the code verifier when authenticating a User.
If there is an issue generating an authorization URL, the API will return the original redirect URI with error
and error_description
query parameters. If provided, the state
value will also be included.
https://your-app.com/callback?error=organization_invalid&error_description=No%20connection%20associated%20with%20organization&state=123456789
Possible error codes and the corresponding descriptions are listed below.
Error code | Description |
---|---|
access_denied | The user denied an OAuth authorization request at the identity provider. |
ambiguous_connection_selector | A connection could not be uniquely identified using the provided connection selector (e.g., organization). This can occur when there are multiple SSO connections under the same organization. If you need multiple SSO connections for an organization, use the connection parameter to identify which connection to use for SSO. |
connection_invalid | There is no connection for the provided ID. |
connection_strategy_invalid | The provider has multiple strategies associated per environment. |
connection_unlinked | The connection associated with the request is unlinked. |
invalid_connection_selector | A valid connection selector query parameter must be provided in order to correctly determine the proper connection to return an authorization URL for. Valid connection selectors are either connection , organization , or provider . |
organization_invalid | There is no organization matching the provided ID. |
oauth_failed | An OAuth authorization request failed for a user. |
server_error | The SSO authentication failed for the user. More detailed errors and steps to resolve are available in the Sessions tab on the connection page in the WorkOS Dashboard. |
Authenticates a user using AuthKit, OAuth or an organization’s SSO connection.
AuthKit handles all authentication methods, however it is conceptually similar to a social login experience. Like OAuth and SSO, AuthKit returns you a code that you can exchange for an authenticated user. See Integrating with AuthKit.
curl --request POST \ --url https://api.workos.com/user_management/authenticate \ --header "Content-Type: application/json" \ -d @- <<BODY { "client_id": "client_123456789", "client_secret": "sk_example_123456789", "grant_type": "authorization_code", "code": "01E2RJ4C05B52KKZ8FSRDAP23J", "ip_address": "192.0.2.1", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36" } BODY
{ "user": { "object": "user", "id": "user_01E4ZCR3C56J083X43JQXF3JK5", "email": "marcelina.davis@example.com", "first_name": "Marcelina", "last_name": "Davis", "email_verified": true, "profile_picture_url": "https://workoscdn.com/images/v1/123abc", "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z" }, "organization_id": "org_01H945H0YD4F97JN9MATX7BYAG", "access_token": "eyJhb.nNzb19vaWRjX2tleV9.lc5Uk4yWVk5In0", "refresh_token": "yAjhKk123NLIjdrBdGZPf8pLIDvK", "impersonator": { "email": "admin@foocorp.com", "reason": "Investigating an issue with the customer's account." } }
POST
/user_management /authenticate
Parameters
Identifies the application making the request to the WorkOS server. You can obtain your client ID from the API Keys page in the dashboard.
Authenticates the application making the request to the WorkOS server. You can obtain your secret key from the API Keys page in the dashboard.
The randomly generated string used to derive the code challenge that was passed to the authorization url as part of the PKCE flow.
This parameter is required when the client secret is not present.
A string constant that distinguishes the method by which your application will receive an access token.
The authorization value which was passed back as a query parameter in the callback to the redirect URI.
The token of an invitation. The invitation should be in the pending state.
When a valid invitation token is specified, the user is able to sign up even if it is disabled in the environment. Additionally, if the invitation was for a specific organization, attaching the token to a user's authenticate call automatically provisions their membership to the organization.
The IP address of the request from the user who is attempting to authenticate.
Refer to your web framework or server documentation for the correct way to obtain the user’s actual IP
address. If your application receives requests from a reverse proxy, you may need to retrieve this from
a special header like X-Forward-For
.
The user agent of the request from the user who is attempting to authenticate. This should be the value
of the User-Agent
header.
Returns
object
The corresponding user object.
The organization the user selected to sign in to.
If the user is a member of multiple organizations, this is the organization the user selected as part of the authentication flow. If the user is a member of only one organization, this is that organization. If the user is not a member of any organizations, this is null
.
A JWT containing information about the session.
Exchange this token for a new access token.
The authentication method used to initiate the session.
The email address of the WorkOS Dashboard user who is impersonating the user. Read more about how impersonation works here.
The justification the impersonator gave for impersonating the user.
Authenticates a user with email and password.
curl --request POST \ --url https://api.workos.com/user_management/authenticate \ --header "Content-Type: application/json" \ -d @- <<BODY { "client_id": "client_123456789", "client_secret": "sk_example_123456789", "grant_type": "password", "email": "marcelina@example.com", "password": "i8uv6g34kd490s", "ip_address": "192.0.2.1", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36" } BODY
{ "user": { "object": "user", "id": "user_01E4ZCR3C56J083X43JQXF3JK5", "email": "marcelina.davis@example.com", "first_name": "Marcelina", "last_name": "Davis", "email_verified": true, "profile_picture_url": "https://workoscdn.com/images/v1/123abc", "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z" }, "organization_id": "org_01H945H0YD4F97JN9MATX7BYAG", "access_token": "eyJhb.nNzb19vaWRjX2tleV9.lc5Uk4yWVk5In0", "refresh_token": "yAjhKk123NLIjdrBdGZPf8pLIDvK" }
POST
/user_management /authenticate
Parameters
Identifies the application making the request to the WorkOS server. You can obtain your client ID from the API Keys page in the dashboard.
Authenticates the application making the request to the WorkOS server. You can obtain your secret key from the API Keys page in the dashboard.
A string constant that distinguishes the method by which your application will receive an access token.
The email address of the user.
The password of the user.
The token of an invitation. The invitation should be in the pending state.
When a valid invitation token is specified, the user is able to sign up even if it is disabled in the environment. Additionally, if the invitation was for a specific organization, attaching the token to a user's authenticate call automatically provisions their membership to the organization.
The IP address of the request from the user who is attempting to authenticate.
Refer to your web framework or server documentation for the correct way to obtain the user’s actual IP
address. If your application receives requests from a reverse proxy, you may need to retrieve this from
a special header like X-Forward-For
.
The user agent of the request from the user who is attempting to authenticate. This should be the value
of the User-Agent
header.
Returns
object
The corresponding user object.
The organization the user selected to sign in to.
If the user is a member of multiple organizations, this is the organization the user selected as part of the authentication flow. If the user is a member of only one organization, this is that organization. If the user is not a member of any organizations, this is null
.
The authentication method used to initiate the session.
Authenticates a user by verifying the Magic Auth code sent to the user’s email.
curl --request POST \ --url https://api.workos.com/user_management/authenticate \ --header "Content-Type: application/json" \ -d @- <<BODY { "client_id": "client_123456789", "client_secret": "sk_example_123456789", "grant_type": "urn:workos:oauth:grant-type:magic-auth:code", "code": "123456", "email": "marcelina.davis@example.com", "ip_address": "192.0.2.1", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36" } BODY
{ "user": { "object": "user", "id": "user_01E4ZCR3C56J083X43JQXF3JK5", "email": "marcelina.davis@example.com", "first_name": "Marcelina", "last_name": "Davis", "email_verified": true, "profile_picture_url": "https://workoscdn.com/images/v1/123abc", "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z" }, "organization_id": "org_01H945H0YD4F97JN9MATX7BYAG" }
POST
/user_management /authenticate
Parameters
Identifies the application making the request to the WorkOS server. You can obtain your client ID from the API Keys page in the dashboard.
Authenticates the application making the request to the WorkOS server. You can obtain your secret key from the API Keys page in the dashboard.
A string constant that distinguishes the method by which your application will receive an access token.
The one-time code that was emailed to the user.
The token of an invitation. The invitation should be in the pending state.
When a valid invitation token is specified, the user is able to sign up even if it is disabled in the environment. Additionally, if the invitation was for a specific organization, attaching the token to a user's authenticate call automatically provisions their membership to the organization.
The email address of the user.
The IP address of the request from the user who is attempting to authenticate.
Refer to your web framework or server documentation for the correct way to obtain the user’s actual IP
address. If your application receives requests from a reverse proxy, you may need to retrieve this from
a special header like X-Forward-For
.
The user agent of the request from the user who is attempting to authenticate. This should be the value
of the User-Agent
header.
Returns
object
The corresponding user object.
The organization the user selected to sign in to.
If the user is a member of multiple organizations, this is the organization the user selected as part of the authentication flow. If the user is a member of only one organization, this is that organization. If the user is not a member of any organizations, this is null
.
The authentication method used to initiate the session.
Use this endpoint to exchange a refresh token for a new access token. Refresh tokens are single use, so a new refresh token is returned.
curl --request POST \ --url https://api.workos.com/user_management/authenticate \ --header "Content-Type: application/json" \ -d @- <<BODY { "client_id": "client_123456789", "client_secret": "sk_test_123", "grant_type": "refresh_token", "refresh_token": "Xw0NsCVXMBf7svAoIoKBmkpEK", "ip_address": "192.0.2.1", "user_agent": "Mozilla/5.0 (X11; Linux x86_64; rv:123.0) Gecko/20100101 Firefox/123.0" } BODY
{ "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6", "refresh_token": "gTsE0Rb9MJq7eL0dUmcGvoCwL" }
POST
/user_management /authenticate
Parameters
Identifies the application making the request to the WorkOS server. You can obtain your client ID from the API Keys page in the dashboard.
Authenticates the application making the request to the WorkOS server. You can obtain your secret key from the API Keys page in the dashboard.
A string constant that distinguishes the method by which your application will receive an access token.
The refresh_token
received from a successful authentication response.
The IP address of the request from the user who is attempting to authenticate.
Refer to your web framework or server documentation for the correct way to obtain the user’s actual IP
address. If your application receives requests from a reverse proxy, you may need to retrieve this from
a special header like X-Forward-For
.
The user agent of the request from the user who is attempting to authenticate. This should be the value
of the User-Agent
header.
Returns
object
A short-lived JWT containing information about the session.
Exchange this token for new access tokens.
Authenticates a user with an unverified email and verifies their email address.
A user with an unverified email address won’t be able to authenticate right away. When they attempt to authenticate with their credentials, the API will return an email verification required error that contains a pending authentication token. Also, WorkOS will automatically send a one-time email verification code to the user’s email address. Use the pending authentication token from the error and the one-time code the user received to authenticate them and to complete the email verification process.
curl --request POST \ --url https://api.workos.com/user_management/authenticate \ --header "Content-Type: application/json" \ -d @- <<BODY { "client_id": "client_123456789", "client_secret": "sk_example_123456789", "grant_type": "urn:workos:oauth:grant-type:email-verification:code", "code": "123456", "pending_authentication_token": "ql1AJgNoLN1tb9llaQ8jyC2dn", "ip_address": "192.0.2.1", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36" } BODY
{ "user": { "object": "user", "id": "user_01E4ZCR3C56J083X43JQXF3JK5", "email": "marcelina.davis@example.com", "first_name": "Marcelina", "last_name": "Davis", "email_verified": true, "profile_picture_url": "https://workoscdn.com/images/v1/123abc", "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z" }, "organization_id": "org_01H945H0YD4F97JN9MATX7BYAG" }
POST
/user_management /authenticate
Parameters
Identifies the application making the request to the WorkOS server. You can obtain your client ID from the API Keys page in the dashboard.
Authenticates the application making the request to the WorkOS server. You can obtain your secret key from the API Keys page in the dashboard.
A string constant that distinguishes the method by which your application will receive an access token.
The one-time email verification code received by the user.
The authentication token returned from a failed authentication attempt due to the corresponding error.
The IP address of the request from the user who is attempting to authenticate.
Refer to your web framework or server documentation for the correct way to obtain the user’s actual IP
address. If your application receives requests from a reverse proxy, you may need to retrieve this from
a special header like X-Forward-For
.
The user agent of the request from the user who is attempting to authenticate. This should be the value
of the User-Agent
header.
Returns
object
The corresponding user object.
The authentication method used to initiate the session.
The organization the user selected to sign in to.
If the user is a member of multiple organizations, this is the organization the user selected as part of the authentication flow. If the user is a member of only one organization, this is that organization. If the user is not a member of any organizations, this is null
.
Authenticates a user enrolled into MFA using time-based one-time password (TOTP).
Users enrolled into MFA are required to enter a TOTP each time they sign in. When they attempt to authenticate with their credentials, the API will return an MFA challenge error that contains a pending authentication token.
To continue with the authentication flow, challenge one of the factors returned by the MFA challenge error response and present a UI to the user to enter the TOTP code. Then, authenticate the user with the TOTP code, the challenge from the factor, and the pending authentication token from the MFA challenge error.
MFA can be enabled via the Authentication page in the WorkOS dashboard.
curl --request POST \ --url https://api.workos.com/user_management/authenticate \ --header "Content-Type: application/json" \ -d @- <<BODY { "client_id": "client_123456789", "client_secret": "sk_example_123456789", "grant_type": "urn:workos:oauth:grant-type:mfa-totp", "code": "123456", "pending_authentication_token": "ql1AJgNoLN1tb9llaQ8jyC2dn", "authenticationChallengeId": "auth_challenge_01FVYZWQTZQ5VB6BC5MPG2EYC5", "ip_address": "192.0.2.1", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36" } BODY
{ "user": { "object": "user", "id": "user_01E4ZCR3C56J083X43JQXF3JK5", "email": "marcelina.davis@example.com", "first_name": "Marcelina", "last_name": "Davis", "email_verified": true, "profile_picture_url": "https://workoscdn.com/images/v1/123abc", "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z" }, "organization_id": "org_01H945H0YD4F97JN9MATX7BYAG" }
POST
/user_management /authenticate
Parameters
Identifies the application making the request to the WorkOS server. You can obtain your client ID from the API Keys page in the dashboard.
Authenticates the application making the request to the WorkOS server. You can obtain your secret key from the API Keys page in the dashboard.
A string constant that distinguishes the method by which your application will receive an access token.
The time-based one-time password generated by the factor that was challenged.
The unique ID of the authentication challenge created for the TOTP factor for which the user is enrolled.
The authentication token returned from a failed authentication attempt due to the corresponding error.
The IP address of the request from the user who is attempting to authenticate.
Refer to your web framework or server documentation for the correct way to obtain the user’s actual IP
address. If your application receives requests from a reverse proxy, you may need to retrieve this from
a special header like X-Forward-For
.
The user agent of the request from the user who is attempting to authenticate. This should be the value
of the User-Agent
header.
Returns
object
The corresponding user object.
The organization the user selected to sign in to.
If the user is a member of multiple organizations, this is the organization the user selected as part of the authentication flow. If the user is a member of only one organization, this is that organization. If the user is not a member of any organizations, this is null
.
The authentication method used to initiate the session.
Authenticates a user into an organization they are a member of.
When a user who is a member of multiple organizations attempts to authenticate with their credentials, the API will return an organization selection error that contains a pending authentication token. To continue with the authentication flow, your application should display the list of organizations for the user to choose.
Use the pending authentication token from the error and the organization the user selected in your UI to complete the authentication.
curl --request POST \ --url https://api.workos.com/user_management/authenticate \ --header "Content-Type: application/json" \ -d @- <<BODY { "client_id": "client_123456789", "client_secret": "sk_example_123456789", "grant_type": "urn:workos:oauth:grant-type:organization-selection", "pending_authentication_token": "ql1AJgNoLN1tb9llaQ8jyC2dn", "organization_id": "org_01H93Z2SYX1D3NJ536M94T8SHP", "ip_address": "192.0.2.1", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36" } BODY
{ "user": { "object": "user", "id": "user_01E4ZCR3C56J083X43JQXF3JK5", "email": "marcelina.davis@example.com", "first_name": "Marcelina", "last_name": "Davis", "email_verified": true, "profile_picture_url": "https://workoscdn.com/images/v1/123abc", "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z" }, "organization_id": "org_01H945H0YD4F97JN9MATX7BYAG" }
POST
/user_management /authenticate
Parameters
Identifies the application making the request to the WorkOS server. You can obtain your client ID from the API Keys page in the dashboard.
Authenticates the application making the request to the WorkOS server. You can obtain your secret key from the API Keys page in the dashboard.
A string constant that distinguishes the method by which your application will receive an access token.
The authentication token returned from a failed authentication attempt due to the corresponding error.
The organization the user selected to sign in to.
The IP address of the request from the user who is attempting to authenticate.
Refer to your web framework or server documentation for the correct way to obtain the user’s actual IP
address. If your application receives requests from a reverse proxy, you may need to retrieve this from
a special header like X-Forward-For
.
The user agent of the request from the user who is attempting to authenticate. This should be the value
of the User-Agent
header.
Returns
object
The corresponding user object.
The organization the user selected to sign in to.
If the user is a member of multiple organizations, this is the organization the user selected as part of the authentication flow. If the user is a member of only one organization, this is that organization. If the user is not a member of any organizations, this is null
.
The authentication method used to initiate the session.
This hosts the public key that is used for verifying access tokens.
curl https://api.workos.com/sso/jwks/client_123456789
https://api.workos.com/sso/jwks/client_123456789
GET
/sso /jwks
Identifies the application making the request to the WorkOS server. You can obtain your client ID from the API Keys page in the dashboard.
Returns
URL that hosts the JWKS for signing access tokens.
The access token that is returned in successful authentication responses is a JWT that can be used to verify that a user has an active session. The JWT is signed by a JWKS which can be retrieved from the WorkOS API.
{ "iss": "https://api.workos.com", "sub": "user_01HBEQKA6K4QJAS93VPE39W1JT", "act": { "sub": "admin@foocorp.com" }, "org_id": "org_01HRDMC6CM357W30QMHMQ96Q0S", "role": "member", "sid": "session_01HQSXZGF8FHF7A9ZZFCW4387R", "jti": "01HQSXZXPPFPKMDD32RKTFY6PV", "exp": 1709193857, "iat": 1709193557 }
Access Token JWT
The issuer of the JWT, will be your custom WorkOS auth domain if set.
The unique ID of the user.
An RFC 8693 compatible claim present when the session was started using impersonation.
The nested sub
claim contains the email adddress of the WorkOS Dashboard user impersonating
the user.
The organization the user selected to sign in to.
If the user is a member of multiple organizations, this is the organization the user selected as part of the authentication flow. If the user is a member of only one organization, this is that organization. If the user is not a member of any organizations, this is null
.
Corresponds to the role on the organization membership
The session ID. You would use this with the logout endpoint.
A unique identifier for this access token.
The token should not be trusted after this time.
The token was issued at this time.
The refresh token can be used to obtain a new access token using the authenticate with refresh token endpoint. Refresh tokens may only be used once. Refreshes will succeed as long as the user's session is still active.
Integrating the authentication API directly requires handling error responses for email verification, MFA challenges, identity linking, and organization selection. One or more of these responses may be returned for an authentication attempt with any authentication method.
Hosted AuthKit handles authentication errors for you and may be a good choice if you prefer a simpler integration.
This error indicates that a user with an unverified email address attempted to authenticate in an environment where email verification is required. It includes a pending authentication token that should be used to complete the authentication.
{ "code": "email_verification_required", "message": "Email ownership must be verified before authentication.", "pending_authentication_token": "YQyCkYfuVw2mI3tzSrk2C1Y7S", "email": "marcelina.davis@example.com" }
email_verification_required
A string constant that distinguishes the error type.
A human-readable message describing the error.
A token that should be used to complete the authentication with a corresponding method after this error occurs.
The email address of the user.
When this error occurs, WorkOS will automatically send a one-time email verification code to the user’s email address and issue a pending authentication token. To complete the authentication process, use the pending authentication token from the error and the one-time code the user received to authenticate them and to verify their email address.
The same applies when a user attempts to authenticate with OAuth or SSO, but there was already an account with a matching unverified email address.
This error indicates that a user who is not enrolled into MFA attempted to authenticate in an environment where MFA is required. It includes a pending authentication token that should be used to authenticate the user once they enroll into MFA.
{ "code": "mfa_enrollment", "message": "The user must enroll in MFA to finish authenticating.", "pending_authentication_token": "YQyCkYfuVw2mI3tzSrk2C1Y7S", "user": { "object": "user", "id": "user_01E4ZCR3C56J083X43JQXF3JK5", "email": "marcelina.davis@example.com", "first_name": "Marcelina", "last_name": "Davis", "email_verified": true, "profile_picture_url": "https://workoscdn.com/images/v1/123abc", "created_at": "2021-06-25T19: 07: 33.155Z", "updated_at": "2021-06-25T19: 07: 33.155Z" } }
mfa_enrollment
A string constant that distinguishes the error type.
A human-readable message describing the error.
A token that should be used to complete the authentication with a corresponding method after this error occurs.
The corresponding user object.
When this error occurs, you’ll need to present an MFA enrollment UI to the user. Once the user has enrolled, present an MFA challenge UI to the user and authenticate them with their TOTP code and the pending authentication token from this error.
MFA can be enabled via the Authentication page in the WorkOS dashboard.
This error indicates that a user enrolled into MFA attempted to authenticate in an environment where MFA is required. It includes a pending authentication token and a list of factors that the user is enrolled in that should be used to complete the authentication.
{ "code": "mfa_challenge", "message": "The user must complete an MFA challenge to finish authenticating.", "pending_authentication_token": "YQyCkYfuVw2mI3tzSrk2C1Y7S", "authentication_factors": [ { "id": "auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ", "type": "totp" } ], "user": { "object": "user", "id": "user_01E4ZCR3C56J083X43JQXF3JK5", "email": "marcelina.davis@example.com", "first_name": "Marcelina", "last_name": "Davis", "email_verified": true, "profile_picture_url": "https://workoscdn.com/images/v1/123abc", "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z" } }
mfa_challenge
When this error occurs, you’ll need to present an MFA challenge UI to the user and authenticate them with their TOTP code, the pending authentication token from this error, and a challenge that corresponds to one of the authentication factors.
MFA can be enabled via the Authentication page in the WorkOS dashboard.
This error indicates that the user is a member of multiple organizations and must select which organization to sign in to. It includes a list of organizations the user is a member of and a pending authentication token that should be used to complete the authentication.
{ "code": "organization_selection_required", "message": "The user must choose an organization to finish their authentication.", "pending_authentication_token": "YQyCkYfuVw2mI3tzSrk2C1Y7S", "organizations": [ { "id": "org_01H93RZAP85YGYZJXYPAZ9QTXF", "name": "Foo Corp" }, { "id": "org_01H93S4E6GB5A8PFNKGTA4S42X", "name": "Bar Corp" } ], "user": { "object": "user", "id": "user_01E4ZCR3C56J083X43JQXF3JK5", "email": "marcelina.davis@example.com", "first_name": "Marcelina", "last_name": "Davis", "email_verified": true, "profile_picture_url": "https://workoscdn.com/images/v1/123abc", "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z" } }
organization_selection_required
A string constant that distinguishes the error type.
A human-readable message describing the error.
A token that should be used to complete the authentication with a corresponding method after this error occurs.
The corresponding user object.
IDs and names of the organizations the user is a member of.
When this error occurs, you’ll need to display the list of organizations that the user is a member of and authenticate them with the selected organization using the pending authentication token from the error.
This error indicates that a user attempted to authenticate into an organization that requires SSO using a different authentication method. It includes a list of SSO connections that may be used to complete the authentication.
{ "error": "sso_required", "error_description": "User must authenticate using one of the matching connections.", "connection_ids": ["conn_01DRF1T7JN6GXS8KHS0WYWX1YD"] }
sso_required
A string constant that distinguishes the error type.
A human-readable message describing the error.
The email of the authenticating user.
A list of SSO connection IDs that the user is required to authenticate with. One of these connections must be used.
A token that should be used to complete the authentication with the authorization_code
grant type after this error occurs.
This may be null
, which indicates that no pending authentication token needs to be passed to the authenticate call.
When this error occurs, you’ll need to use one of the SSO connections from the error to get the authorization URL and redirect the user to that URL to complete the authentication with the organization’s identity provider.
This error indicates that a user attempted to authenticate with an authentication method that is not allowed by the organization that has domain captured this user. It includes all the possible methods the user can authentication.
{ "error": "organization_authentication_methods_required", "error_description": "User must authenticate using one of the methods allowed by the organization.", "sso_connection_ids": ["conn_01DRF1T7JN6GXS8KHS0WYWX1YD"], "auth_methods": { "github_oauth": false, "google_oauth": true, "magic_auth": false, "microsoft_oauth": false, "password": false } }
organization_authentication_methods_required
A string constant that distinguishes the error type.
A human-readable message describing the error.
The email of the authenticating user.
A list of SSO connection IDs that the user is required to authenticate with. One of these connections must be used.
Whether or not GitHub OAuth is enabled for the organization.
Whether or not Google OAuth is enabled for the organization.
Whether or not Magic Auth is enabled for the organization.
Whether or not Microsoft OAuth is enabled for the organization.
Whether or not password authentication is enabled for the organization.
When this error occurs, you’ll need to present the user with these options so they can choose which method to continue authentication.
Magic Auth is a passwordless authentication method that allows users to sign in or sign up via a unique, six digit one-time-use code sent to their email inbox. To verify the code, authenticate the user with Magic Auth.
{ "id": "magic_auth_01E4ZCR3C56J083X43JQXF3JK5", "user_id": "user_01HWWYEH2NPT48X82ZT23K5AX4", "email": "marcelina.davis@example.com", "expires_at": "2021-07-01T19:07:33.155Z", "code": "123456", "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z" }
Get the details of an existing Magic Auth code that can be used to send an email to a user for authentication.
curl https://api.workos.com/user_management/magic_auth/magic_auth_01E4ZCR3C56J083X43JQXF3JK5 \ --header "Authorization: Bearer sk_example_123456789"
{ "id": "magic_auth_01E4ZCR3C56J083X43JQXF3JK5", "user_id": "user_01HWWYEH2NPT48X82ZT23K5AX4", "email": "marcelina.davis@example.com", "expires_at": "2021-07-01T19:07:33.155Z", "code": "123456", "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z" }
GET
/user_management /magic_auth /:id
Parameters
The unique ID of the Magic Auth code.
Returns
Creates a one-time authentication code that can be sent to the user’s email address. The code expires in 10 minutes. To verify the code, authenticate the user with Magic Auth.
curl --request POST \ --url https://api.workos.com/user_management/magic_auth \ --header "Authorization: Bearer sk_example_123456789" \ -d email="marcelina.davis@example.com"
{ "id": "magic_auth_01E4ZCR3C56J083X43JQXF3JK5", "user_id": "user_01HWWYEH2NPT48X82ZT23K5AX4", "email": "marcelina.davis@example.com", "expires_at": "2021-07-01T19:07:33.155Z", "code": "123456", "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z" }
POST
Sends email/user_management /magic_auth
Parameters
The email address of the user.
The token of an invitation. The invitation should be in the pending state.
When a valid invitation token is specified, the user is able to sign up even if it is disabled in the environment. Additionally, if the invitation was for a specific organization, attaching the token to a user's authenticate call automatically provisions their membership to the organization.
Returns
Sends a one-time authentication code to the user’s email address. The code expires in 10 minutes. To verify the code, authenticate the user with Magic Auth.
curl https://api.workos.com/user_management/magic_auth/send \ --header "Authorization: Bearer sk_example_123456789" \ -d email="marcelina.davis@example.com"
POST
Sends email/user_management /magic_auth /send
Parameters
The email address of the user.
Enroll users in multi-factor authentication for an additional layer of security. MFA can be enabled via the Authentication page in the WorkOS dashboard.
Represents an authentication factor.
{ "object": "authentication_factor", "id": "auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ", "created_at": "2022-02-15T15:14:19.392Z", "updated_at": "2022-02-15T15:14:19.392Z", "type": "totp", "totp": { "issuer": "Foo Corp", "user": "alan.turing@example.com", "qr_code": "data:image/png;base64,{base64EncodedPng}", "secret": "NAGCCFS3EYRB422HNAKAKY3XDUORMSRF", "uri": "otpauth://totp/FooCorp:alan.turing@example.com?secret=NAGCCFS3EYRB422HNAKAKY3XDUORMSRF&issuer=FooCorp" }, "userId": "user_01FVYZ5QM8N98T9ME5BCB2BBMJ" }
authentication_factor
Distinguishes the authentication factor object.
The unique ID of the factor.
The timestamp when the factor was created.
The timestamp when the factor was last updated.
The type of the factor to enroll. The only available option is TOTP.
Your application or company name displayed in the user’s authenticator app. Defaults to your WorkOS team name.
The user’s account name displayed in their authenticator app. Defaults to the user’s email.
Base64 encoded image containing scannable QR code.
TOTP secret that can be manually entered into some authenticator apps in place of scanning a QR code.
The otpauth
URI that is encoded by the provided qr_code
.
The ID of the user.
Represents a challenge of an authentication factor.
{ "object": "authentication_challenge", "id": "auth_challenge_01FVYZWQTZQ5VB6BC5MPG2EYC5", "created_at": "2022-02-15T15:26:53.274Z", "updated_at": "2022-02-15T15:26:53.274Z", "expires_at": "2022-02-15T15:36:53.279Z", "authentication_factor_id": "auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ" }
authentication_challenge
Distinguishes the authentication challenge object.
The unique ID of the authentication challenge.
The timestamp when the challenge was created.
The timestamp when the challenge was last updated.
The timestamp when the challenge will expire. Does not apply to TOTP factors.
The unique ID of the authentication factor the challenge belongs to.
Enrolls a user in a new authentication factor.
curl --request POST \ --url https://api.workos.com/user_management/users/user_01E4ZCR3C56J083X43JQXF3JK5/auth_factors \ --header "Authorization: Bearer sk_example_123456789" \ --header "Content-Type: application/json" \ -d @- <<BODY { "type": "totp", "totp_issuer": "Foo Corp", "totp_user": "bob@example.com" } BODY
POST
/user_management /users /:id /auth_factors
Parameters
The unique ID of the user to enroll the auth factor.
The type of the factor to enroll. The only available option is TOTP.
Your application or company name displayed in the user’s authenticator app. Defaults to your WorkOS team name.
The user’s account name displayed in their authenticator app. Defaults to the user’s email.
Returns
object
The authentication challenge object that is used to complete the authentication process.
The authentication factor object that represents the additional authentication method used on top of the existing authentication strategy.
Lists the authentication factors for a user.
curl https://api.workos.com/user_management/users/user_01E4ZCR3C56J083X43JQXF3JK5/auth_factors \ --header "Authorization: Bearer sk_example_123456789"
GET
/user_management /users /:id /auth_factors
Parameters
The user ID to list the authentication factors for.
Returns
object
List of authentication factors.
An object ID that defines your place in the list. When the ID is not present, you are at the end of the list.
For example, if you make a list request and receive 100 objects, ending with "obj_123"
, your subsequent call can include before="obj_123"
to fetch a new batch of objects before "obj_123"
.
An object ID that defines your place in the list. When the ID is not present, you are at the end of the list.
For example, if you make a list request and receive 100 objects, ending with "obj_123"
, your subsequent call can include after="obj_123"
to fetch a new batch of objects after "obj_123"
.
Sends an email with a link that contains a password reset token as a query parameter.
curl --request POST \ --url https://api.workos.com/user_management/password_reset/send \ --header "Content-Type: application/json" \ --header "Authorization: Bearer sk_example_123456789" \ -d @- <<BODY { "email": "marcelina@example.com", "password_reset_url": "https://your-app.com/reset-password" } BODY
POST
Sends email/user_management /password_reset /send
Parameters
The email address of the user who requested to reset their password.
The URL to include in the email. A token
query parameter will be added to this URL to complete the password reset process in the next step.
Sets a new password using the token
query parameter from the link that the user received.
curl --request POST \ --url https://api.workos.com/user_management/password_reset/confirm \ --header "Authorization: Bearer sk_example_123456789" \ --header "Content-Type: application/json" \ -d @- <<BODY { "token": "stpIJ48IFJt0HhSIqjf8eppe0", "new_password": "i8uv6g34kd490s" } BODY
POST
/user_management /password_reset /confirm
Parameters
The token
query parameter from the password reset URL.
The new password to set for the user.
Returns
object
The corresponding user object.
An organization membership is a top-level resource that represents a user’s relationship with an organization. A user may be a member of zero, one, or many organizations.
See the events reference documentation for the organization membership events.
{ "object": "organization_membership", "id": "om_01E4ZCR3C56J083X43JQXF3JK5", "user_id": "user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E", "organization_id": "org_01E4ZCR3C56J083X43JQXF3JK5", "role": { "slug": "admin" }, "status": "active", "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z" }
organization_membership
Distinguishes the organization membership object.
The unique ID of the organization membership.
The ID of the user.
The ID of the organization which the user belongs to.
The unique role identifier
The status of the organization membership. One of active
, inactive
, or pending
.
The timestamp when the organization membership was created.
The timestamp when the organization membership was last updated.
Get the details of an existing organization membership.
curl https://api.workos.com/user_management/organization_memberships/om_01E4ZCR3C56J083X43JQXF3JK5 \ --header "Authorization: Bearer sk_example_123456789"
{ "object": "organization_membership", "id": "om_01E4ZCR3C56J083X43JQXF3JK5", "user_id": "user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E", "organization_id": "org_01E4ZCR3C56J083X43JQXF3JK5", "role": { "slug": "member" }, "status": "active", "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z" }
GET
/user_management /organization_memberships /:id
Parameters
The unique ID of the organization membership.
Returns
Get a list of all organization memberships matching the criteria specified.
curl https://api.workos.com/user_management/organization_memberships \ --header "Authorization: Bearer sk_example_123456789"
{ "data": [ { "object": "organization_membership", "id": "om_01E4ZCR3C56J083X43JQXF3JK5", "user_id": "user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E", "organization_id": "org_01E4ZCR3C56J083X43JQXF3JK5", "role": { "slug": "member" }, "status": "active", "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z" } ], "list_metadata": { "before": "om_01E4ZCR3C56J083X43JQXF3JK5", "after": "om_01EJBGJT2PC6638TN5Y380M40Z" } }
GET
/user_management /organization_memberships
Parameters
The ID of the user.
The ID of the organization which the user belongs to.
Filter by the status of the organization membership. Array including any of active
, inactive
, or pending
.
Upper limit on the number of objects to return, between 1
and 100
. The default value is 10
.
An object ID that defines your place in the list. When the ID is not present, you are at the end of the list.
For example, if you make a list request and receive 100 objects, ending with "obj_123"
, your subsequent call can include before="obj_123"
to fetch a new batch of objects before "obj_123"
.
An object ID that defines your place in the list. When the ID is not present, you are at the end of the list.
For example, if you make a list request and receive 100 objects, ending with "obj_123"
, your subsequent call can include after="obj_123"
to fetch a new batch of objects after "obj_123"
.
Order the results by the creation time. Supported values are "asc"
and "desc"
for showing older and newer records first respectively. Default order is descending.
Returns
object
Array of organization memberships ordered by creation time.
An object ID that defines your place in the list. When the ID is not present, you are at the end of the list.
For example, if you make a list request and receive 100 objects, ending with "obj_123"
, your subsequent call can include before="obj_123"
to fetch a new batch of objects before "obj_123"
.
An object ID that defines your place in the list. When the ID is not present, you are at the end of the list.
For example, if you make a list request and receive 100 objects, ending with "obj_123"
, your subsequent call can include after="obj_123"
to fetch a new batch of objects after "obj_123"
.
Creates a new active
organization membership for the given organization and user.
Calling this API with an organization and user that match an inactive
organization membership will activate the membership with the specified role.
curl --request POST \ --url https://api.workos.com/user_management/organization_memberships \ --header "Authorization: Bearer sk_example_123456789" \ -d user_id="user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E" \ -d organization_id="org_01E4ZCR3C56J083X43JQXF3JK5" \ -d role_slug="admin"
{ "object": "organization_membership", "id": "om_01E4ZCR3C56J083X43JQXF3JK5", "user_id": "user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E", "organization_id": "org_01E4ZCR3C56J083X43JQXF3JK5", "role": { "slug": "admin" }, "status": "active", "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z" }
POST
/user_management /organization_memberships
Parameters
The ID of the user.
The ID of the organization which the user belongs to.
The unique role identifier. Defaults to member
.
Returns
Update the details of an existing organization membership.
curl --request PUT \ --url https://api.workos.com/user_management/organization_memberships/om_01E4ZCR3C56J083X43JQXF3JK5 \ --header "Authorization: Bearer sk_example_123456789" \ --header "Content-Type: application/json" \ -d @- <<BODY { "role_slug": "admin" } BODY
{ "object": "organization_membership", "id": "om_01E4ZCR3C56J083X43JQXF3JK5", "user_id": "user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E", "organization_id": "org_01E4ZCR3C56J083X43JQXF3JK5", "role": { "slug": "admin" }, "status": "active", "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-27T19:07:33.278Z" }
PUT
/user_management /organization_memberships /:id
Parameters
The unique ID of the organization membership.
The unique role identifier.
Returns
Deletes an existing organization membership.
curl --request DELETE \ --url https://api.workos.com/user_management/organization_memberships/om_01E4ZCR3C56J083X43JQXF3JK5 \ --header "Authorization: Bearer sk_example_123456789"
DELETE
/user_management /organization_memberships /:id
Parameters
The unique ID of the organization membership.
Deactivates an active
organization membership. Emits an organization_membership.updated event upon successful deactivation.
inactive
membership is a no-op and does not emit an event.pending
membership returns an error. This membership should be deleted instead.
curl --request PUT \ --url https://api.workos.com/user_management/organization_memberships/om_01E4ZCR3C56J083X43JQXF3JK5/deactivate \ --header "Authorization: Bearer sk_example_123456789"
{ "object": "organization_membership", "id": "om_01E4ZCR3C56J083X43JQXF3JK5", "user_id": "user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E", "organization_id": "org_01E4ZCR3C56J083X43JQXF3JK5", "role": { "slug": "member" }, "status": "inactive", "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z" }
PUT
/user_management /organization_memberships /:id /deactivate
Parameters
The unique ID of the organization membership.
Returns
Reactivates an inactive
organization membership, retaining the pre-existing role. Emits an organization_membership.updated event upon successful reactivation.
active
membership is a no-op and does not emit an event.pending
membership returns an error. The user needs to accept the invitation instead.
curl --request PUT \ --url https://api.workos.com/user_management/organization_memberships/om_01E4ZCR3C56J083X43JQXF3JK5/reactivate \ --header "Authorization: Bearer sk_example_123456789"
{ "object": "organization_membership", "id": "om_01E4ZCR3C56J083X43JQXF3JK5", "user_id": "user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E", "organization_id": "org_01E4ZCR3C56J083X43JQXF3JK5", "role": { "slug": "member" }, "status": "active", "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z" }
PUT
/user_management /organization_memberships /:id /reactivate
Parameters
The unique ID of the organization membership.
Returns
An email invitation allows the recipient to sign up for your app and join a specific organization. When an invitation is accepted, a user and a corresponding organization membership are created.
Users may be invited to your app without joining an organization, or they may be invited to join an organization if they already have an account. Invitations may be also issued on behalf of another user. In this case, the invitation email will mention the name of the user who invited the recipient.
{ "id": "invitation_01E4ZCR3C56J083X43JQXF3JK5", "email": "marcelina.davis@example.com", "state": "pending", "accepted_at": null, "revoked_at": null, "expires_at": "2021-07-01T19:07:33.155Z", "token": "Z1uX3RbwcIl5fIGJJJCXXisdI", "accept_invitation_url": "https://myauthkit.com/invite?invitation_token=Z1uX3RbwcIl5fIGJJJCXXisdI", "organization_id": "org_01E4ZCR3C56J083X43JQXF3JK5", "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z" }
Get the details of an existing invitation.
curl https://api.workos.com/user_management/invitations/invitation_123456789 \ --header "Authorization: Bearer sk_example_123456789"
{ "object": "invitation", "id": "invitation_01E4ZCR3C56J083X43JQXF3JK5", "email": "marcelina.davis@example.com", "state": "pending", "accepted_at": null, "revoked_at": null, "expires_at": "2021-07-01T19:07:33.155Z", "token": "Z1uX3RbwcIl5fIGJJJCXXisdI", "accept_invitation_url": "https://myauthkit.com/invite?invitation_token=Z1uX3RbwcIl5fIGJJJCXXisdI", "organization_id": "org_01E4ZCR3C56J083X43JQXF3JK5", "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z" }
Get a list of all of invitations matching the criteria specified.
curl https://api.workos.com/user_management/invitations \ --header "Authorization: Bearer sk_example_123456789"
{ "data": [ { "object": "invitation", "id": "invitation_01E4ZCR3C56J083X43JQXF3JK5", "email": "marcelina.davis@example.com", "state": "pending", "accepted_at": null, "revoked_at": null, "expires_at": "2021-07-01T19:07:33.155Z", "token": "Z1uX3RbwcIl5fIGJJJCXXisdI", "accept_invitation_url": "https://myauthkit.com/invite?invitation_token=Z1uX3RbwcIl5fIGJJJCXXisdI", "organization_id": "org_01E4ZCR3C56J083X43JQXF3JK5", "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z" } ], "list_metadata": { "before": "invitation_01E4ZCR3C56J083X43JQXF3JK5", "after": "invitation_01EJBGJT2PC6638TN5Y380M40Z" } }
GET
/user_management /invitations
Parameters
The email address of the recipient.
The ID of the organization that the recipient will join.
Upper limit on the number of objects to return, between 1
and 100
. The default value is 10
.
An object ID that defines your place in the list. When the ID is not present, you are at the end of the list.
For example, if you make a list request and receive 100 objects, ending with "obj_123"
, your subsequent call can include before="obj_123"
to fetch a new batch of objects before "obj_123"
.
An object ID that defines your place in the list. When the ID is not present, you are at the end of the list.
For example, if you make a list request and receive 100 objects, ending with "obj_123"
, your subsequent call can include after="obj_123"
to fetch a new batch of objects after "obj_123"
.
Order the results by the creation time. Supported values are "asc"
and "desc"
for showing older and newer records first respectively. Default order is descending.
Returns
object
Array of invitations ordered by creation time.
An object ID that defines your place in the list. When the ID is not present, you are at the end of the list.
For example, if you make a list request and receive 100 objects, ending with "obj_123"
, your subsequent call can include before="obj_123"
to fetch a new batch of objects before "obj_123"
.
An object ID that defines your place in the list. When the ID is not present, you are at the end of the list.
For example, if you make a list request and receive 100 objects, ending with "obj_123"
, your subsequent call can include after="obj_123"
to fetch a new batch of objects after "obj_123"
.
Sends an invitation email to the recipient.
curl --request POST \ --url https://api.workos.com/user_management/invitations \ --header "Authorization: Bearer sk_example_123456789" \ -d email="marcelina.davis@example.com"
{ "object": "invitation", "id": "invitation_01E4ZCR3C56J083X43JQXF3JK5", "email": "marcelina.davis@example.com", "state": "pending", "accepted_at": null, "revoked_at": null, "expires_at": "2021-07-01T19:07:33.155Z", "token": "Z1uX3RbwcIl5fIGJJJCXXisdI", "accept_invitation_url": "https://myauthkit.com/invite?invitation_token=Z1uX3RbwcIl5fIGJJJCXXisdI", "organization_id": "org_01E4ZCR3C56J083X43JQXF3JK5", "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z" }
POST
Sends email/user_management /invitations
Parameters
The email address of the recipient.
The ID of the organization that the recipient will join.
How many days the invitations will be valid for.
Must be between 1 and 30 days. Defaults to 7 days if not specified.
The ID of the user who invites the recipient. The invitation email will mention the name of this user.
The role that the recipient will receive when they join the organization in the invitation.
Returns
Revokes an existing invitation.
curl --request POST \ --url https://api.workos.com/user_management/invitations/invitation_01E4ZCR3C56J083X43JQXF3JK5/revoke \ --header "Authorization: Bearer sk_example_123456789"
{ "object": "invitation", "id": "invitation_01E4ZCR3C56J083X43JQXF3JK5", "email": "marcelina.davis@example.com", "state": "revoked", "accepted_at": null, "revoked_at": "2021-06-27T19:07:33.155Z", "expires_at": "2021-07-01T19:07:33.155Z", "token": "Z1uX3RbwcIl5fIGJJJCXXisdI", "accept_invitation_url": "https://myauthkit.com/invite?invitation_token=Z1uX3RbwcIl5fIGJJJCXXisdI", "organization_id": "org_01E4ZCR3C56J083X43JQXF3JK5", "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z" }
POST
/user_management /invitations /:id /revoke
Parameters
The unique ID of the invitation.
Returns
End a user's session. The user's browser should be redirected to this URL.
curl https://api.workos.com/user_management/sessions/logout -G \ -d session_id=session_01HQAG1HENBZMAZD82YRXDFC0B
https://api.workos.com/user_management/user_management/sessions/logout? session_id=session_01HQAG1HENBZMAZD82YRXDFC0B
GET
/user_management /sessions /logout
Parameters
The ID of the session that is ending. This can be extracted from the sid
claim of the access token.
Returns
The user's browser should be redirected to this URL to sign them out.
The Single Sign-On API has been modeled to meet the OAuth 2.0 framework specification. As a result, authentication flows constructed using the Single Sign-On API replicate the OAuth 2.0 protocol flow.
To automatically respond to changes in your SSO connections, use the Connection events.
Generates an OAuth 2.0 authorization URL to authenticate a user with SSO.
curl https://api.workos.com/sso/authorize -G \ -d response_type=code \ -d client_id=client_123456789 \ -d redirect_uri=https://your-app.com/callback \ -d state=dj1kUXc0dzlXZ1hjUQ== \ -d connection=conn_01E4ZCR3C56J083X43JQXF3JK5
https://api.workos.com/sso/authorize? response_type=code& client_id=client_123456789& redirect_uri=https://your-app.com/callback& state=dj1kUXc0dzlXZ1hjUQ==& connection=conn_01E4ZCR3C56J083X43JQXF3JK5
GET
/sso /authorize
The only valid option for the response type parameter is "code"
.
The "code"
parameter value initiates an authorization code grant type. This grant type allows you to exchange an authorization code for an access token during the redirect that takes place after a user has authenticated with an identity provider.
Identifies the application making the request to the WorkOS server. You can obtain your client ID from the API Keys page in the dashboard.
Where to redirect the user after they complete the authentication process. You must use one of the redirect URIs configured via the Redirects page on the dashboard.
Used to initiate SSO for a connection. The value should be a WorkOS connection ID.
You 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.
Used to initiate SSO for an organization. The value should be a WorkOS organization ID.
You can persist the WorkOS organization ID with application user or team identifiers. WorkOS will use the organization ID to determine the appropriate connection and the IdP to direct the user to for authentication.
Used to initiate authentication with Google, Microsoft, or GitHub OAuth.
An optional parameter that can be used to encode arbitrary information to help restore application state between redirects. If included, the redirect URI received from WorkOS will contain the exact state
that was passed.
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 supported for OAuth, OpenID Connect, Okta, and Entra ID connections.
Can be used to pre-fill the domain field when initiating authentication with Microsoft OAuth or with a Google SAML connection type.
Returns
An OAuth 2.0 authorization URL.
You’ll have to specify the user’s connection, organization, or OAuth provider as a parameter. These connection selectors are mutually exclusive, and exactly one must be provided. The generated URL automatically directs the 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 sign-in flow.
In the OAuth 2.0 protocol, a redirect URI is the location that the user is redirected to once they have successfully authenticated with their identity provider.
When redirecting the user, WorkOS will generate an authorization code and pass it to your redirect URI as a code
query parameter, your app will use this code to get the user’s profile. Additionally, WorkOS can pass a state
parameter back to your application that you may use to encode arbitrary information to restore your application state between the redirects.
https://your-app.com/callback?code=01E2RJ4C05B52KKZ8FSRDAP23J&state=dj1kUXc0dzlXZ1hjUQ==
You’ll need to configure the allowed redirect URIs for your application via the Redirects page in the dashboard. Without a valid redirect URI, your users will be unable to sign in. Make sure that the redirect URI you use as a parameter to get the authorization URL matches one of the redirect URIs you have configured in the dashboard.
Redirect URIs follow stricter requirements in production environments:
HTTPS
protocol is required in production environmentsHTTP
and localhost
are allowed in staging environmentsIf there is an issue generating an authorization URL, the API will return the original redirect URI with error
and error_description
query parameters. If provided, the state
value will also be included.
https://your-app.com/callback?error=organization_invalid&error_description=No%20connection%20associated%20with%20organization&state=123456789
Possible error codes and the corresponding descriptions are listed below.
Error code | Description |
---|---|
access_denied | The user denied an OAuth authorization request at the identity provider. |
ambiguous_connection_selector | A connection could not be uniquely identified using the provided connection selector (e.g., organization). This can occur when there are multiple SSO connections under the same organization. If you need multiple SSO connections for an organization, use the connection parameter to identify which connection to use for SSO. |
connection_domain_invalid | There is no connection for the provided domain. |
connection_invalid | There is no connection for the provided ID. |
connection_strategy_invalid | The provider has multiple strategies associated per environment. |
connection_unlinked | The connection associated with the request is unlinked. |
domain_connection_selector_not_allowed | This is a legacy error code that only applies if using the deprecated “domain” query parameter which is no longer valid for this endpoint. Use the “organization” or “connection” query parameters to target a connection instead. |
invalid_connection_selector | A valid connection selector query parameter must be provided in order to correctly determine the proper connection to return an authorization URL for. Valid connection selectors are either connection , organization , or provider . |
organization_invalid | There is no organization matching the provided ID. |
oauth_failed | An OAuth authorization request failed for a user. |
profile_not_allowed_outside_organization | A profile was received that has an email that is outside the organization’s domain 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. |
server_error | The SSO authentication failed for the user. More detailed errors and steps to resolve are available in the Sessions tab on the connection page in the WorkOS Dashboard. |
A Profile is an object that represents an authenticated user. The Profile object contains information relevant to a user in the form of normalized and raw attributes.
After receiving the Profile for an authenticated user, use the Profile object attributes to persist relevant data to your application’s user model for the specific, authenticated user.
No Profile attributes can be returned other than the normalized attributes listed below, and the raw attributes returned by an Identity Provider.
{ "object": "profile", "id": "prof_01DMC79VCBZ0NY2099737PSVF1", "connection_id": "conn_01E4ZCR3C56J083X43JQXF3JK5", "connection_type": "OktaSAML", "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY", "email": "todd@example.com", "first_name": "Todd", "last_name": "Rundgren", "idp_id": "00u1a0ufowBJlzPlk357", "groups": ["Admins", "Developers", "Engineering"], "raw_attributes": {} }
profile
Distinguishes the Profile object.
Unique identifier for the user, assigned by WorkOS.
This value can be persisted to the Developer’s user model and used as a unique key for identifying a specific user.
Unique identifier for the Connection to which the Profile belongs.
The type of the SSO Connection used to authenticate the user. The Connection type may be used to dynamically generate authorization URLs.
Possible values:
ADFSSAML
AdpOidc
Auth0SAML
AzureSAML
CasSAML
ClassLinkSAML
CloudflareSAML
CyberArkSAML
DuoSAML
GenericOIDC
GenericSAML
GitHubOAuth
GoogleOAuth
GoogleSAML
JumpCloudSAML
KeycloakSAML
LastPassSAML
LoginGovOidc
MagicLink
MicrosoftOAuth
MiniOrangeSAML
NetIqSAML
OktaSAML
OneLoginSAML
OracleSAML
PingFederateSAML
PingOneSAML
RipplingSAML
SalesforceSAML
ShibbolethGenericSAML
ShibbolethSAML
SimpleSamlPhpSAML
VMwareSAML
Unique identifier for the Organization in which the Connection resides.
The user’s email address.
The user’s first name.
The user’s last name.
Unique identifier for the user, assigned by the Identity Provider. Different Identity Providers use different ID formats.
One possible use case for idp_id is associating a user’s SSO Profile with any relevant Directory Sync actions related to that user.
List of groups the user is a member of, used in JIT Provisioning and Role Mapping.
This feature is currently in beta, contact customer support for more information.
Object of key-value pairs containing relevant user data from the Identity Provider.
Raw attributes are an extended set of information one can expect for each user Profile. These raw attributes will vary by Identity Provider and Identity Provider configuration.
Get an access token along with the user Profile using the code passed to your Redirect URI.
curl -X POST "https://api.workos.com/sso/token" \ -d 'client_id=client_123456789' \ -d 'client_secret=sk_example_123456789' \ -d 'grant_type=authorization_code' \ -d 'code=01E2RJ4C05B52KKZ8FSRDAP23J'
{ "access_token": "01DMEK0J53CVMC32CK5SE0KZ8Q", "profile": { "object": "profile", "id": "prof_01DMC79VCBZ0NY2099737PSVF1", "connection_id": "conn_01E4ZCR3C56J083X43JQXF3JK5", "connection_type": "OktaSAML", "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY", "email": "todd@example.com", "first_name": "Todd", "last_name": "Rundgren", "idp_id": "00u1a0ufowBJlzPlk357", "groups": ["Admins", "Developers", "Engineering"], "raw_attributes": {} } }
POST
/sso /token
Parameters
Identifies the application making the request to the WorkOS server. You can obtain your client ID from the API Keys page in the dashboard.
Authenticates the application making the request to the WorkOS server. You can obtain your secret key from the API Keys page in the dashboard.
The method by which your application will receive an access token. This value should be authorization_code
.
The authorization value which was passed back as a query parameter in the callback to the Redirect URI.
Returns
object
An access token that can be exchanged for a user profile. Access tokens expire 5 minutes after they’re created.
The user Profile object.
Exchange an access token for a user’s Profile. Because this profile is returned in the Get a Profile and Token endpoint your application usually does not need to call this endpoint. It is available for any authentication flows that require an additional endpoint to retrieve a user’s profile.
curl https://api.workos.com/sso/profile \ --header "Authorization: Bearer 01DMEK0J53CVMC32CK5SE0KZ8Q"
{ "object": "profile", "id": "prof_01DMC79VCBZ0NY2099737PSVF1", "connection_id": "conn_01E4ZCR3C56J083X43JQXF3JK5", "connection_type": "OktaSAML", "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY", "email": "todd@example.com", "first_name": "Todd", "last_name": "Rundgren", "idp_id": "00u1a0ufowBJlzPlk357", "groups": ["Admins", "Developers", "Engineering"], "raw_attributes": {} }
GET
/sso /profile
Parameters
The authorization value which was returned along with the profile when calling the Get a Profile and Token endpoint.
Returns
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. 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.
See the events reference documentation for the connection events.
{ "object": "connection", "id": "conn_01E4ZCR3C56J083X43JQXF3JK5", "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY", "connection_type": "OktaSAML", "name": "Foo Corp", "state": "active", "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z", "domains": [ { "id": "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A", "object": "connection_domain", "domain": "foo-corp.com" } ] }
connection
Distinguishes the Connection object.
Unique identifier for the Connection.
Unique identifier for the Organization in which the Connection resides.
The type of the SSO Connection used to authenticate the user. The Connection type may be used to dynamically generate authorization URLs.
Possible values:
ADFSSAML
AdpOidc
Auth0SAML
AzureSAML
CasSAML
ClassLinkSAML
CloudflareSAML
CyberArkSAML
DuoSAML
GenericOIDC
GenericSAML
GitHubOAuth
GoogleOAuth
GoogleSAML
JumpCloudSAML
KeycloakSAML
LastPassSAML
LoginGovOidc
MagicLink
MicrosoftOAuth
MiniOrangeSAML
NetIqSAML
OktaSAML
OneLoginSAML
OracleSAML
PingFederateSAML
PingOneSAML
RipplingSAML
SalesforceSAML
ShibbolethGenericSAML
ShibbolethSAML
SimpleSamlPhpSAML
VMwareSAML
A human-readable name for the Connection. This will most commonly be the organization's name.
Indicates whether a Connection is able to authenticate users. Possible values:
active
inactive
validating
Connections that can’t authenticate users are inactive
. When a new connection is configured, it transitions to the validating
state until its first successful authentication. After it successfully authorizes a user for the first time, the connection state changes to active
.
The timestamp when the Connection was created.
The timestamp when the Connection was last updated.
List of Organization Domains.
Get the details of an existing connection.
curl https://api.workos.com/connections/conn_01E2NPPCT7XQ2MVVYDHWGK1WN4 \ --header "Authorization: Bearer sk_example_123456789"
{ "object": "connection", "id": "conn_01E4ZCR3C56J083X43JQXF3JK5", "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY", "connection_type": "OktaSAML", "name": "Foo Corp", "state": "active", "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z", "domains": [ { "id": "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A", "object": "connection_domain", "domain": "foo-corp.com" } ] }
Get a list of all of your existing connections matching the criteria specified.
curl https://api.workos.com/connections \ --header "Authorization: Bearer sk_example_123456789"
{ "data": [ { "object": "connection", "id": "conn_01E4ZCR3C56J083X43JQXF3JK5", "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY", "connection_type": "GoogleOAuth", "name": "Foo Corp", "state": "active", "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:08:33.155Z" }, { "object": "connection", "id": "conn_01E2NPPCT7XQ2MVVYDHWGK1WN4", "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY", "connection_type": "OktaSAML", "name": "Example Co", "state": "active", "created_at": "2021-06-25T19:09:33.155Z", "updated_at": "2021-06-25T19:10:33.155Z" } ], "list_metadata": { "before": "conn_01E2NPPCT7XQ2MVVYDHWGK1WN4", "after": null } }
GET
/connections
Parameters
Filter Connections by their type.
Filter Connections by their associated domain.
Filter Connections by their associated organization.
An object ID that defines your place in the list. When the ID is not present, you are at the end of the list.
For example, if you make a list request and receive 100 objects, ending with "obj_123"
, your subsequent call can include after="obj_123"
to fetch a new batch of objects after "obj_123"
.
An object ID that defines your place in the list. When the ID is not present, you are at the end of the list.
For example, if you make a list request and receive 100 objects, ending with "obj_123"
, your subsequent call can include before="obj_123"
to fetch a new batch of objects before "obj_123"
.
Upper limit on the number of objects to return, between 1
and 100
. The default value is 10
.
Order the results by the creation time. Supported values are "asc"
and "desc"
for showing older and newer records first respectively. Default order is descending.
Returns
object
An array of Connections ordered by creation time.
An object ID that defines your place in the list. When the ID is not present, you are at the end of the list.
For example, if you make a list request and receive 100 objects, ending with "obj_123"
, your subsequent call can include before="obj_123"
to fetch a new batch of objects before "obj_123"
.
An object ID that defines your place in the list. When the ID is not present, you are at the end of the list.
For example, if you make a list request and receive 100 objects, ending with "obj_123"
, your subsequent call can include after="obj_123"
to fetch a new batch of objects after "obj_123"
.
Delete an existing connection.
curl --request DELETE \ --url https://api.workos.com/connections/conn_01E2NPPCT7XQ2MVVYDHWGK1WN4 \ --header "Authorization: Bearer sk_example_123456789"
DELETE
/connections /:id
Parameters
Unique identifier for the Connection.
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 the organization's access rules, groups, and users by integrating webhooks into your application.
To automatically respond to changes in the connected directories and thier users and groups, use the Directory Sync events.
A directory stores information about an organization's employee management system.
Synchronizing with a directory enables you to receive changes to an organization’s user and group structure.
Directory providers vary in implementation details and may require different sets of fields for integration, such as API keys, subdomains, endpoints, usernames, etc. Where available, the WorkOS API will provide these fields when fetching directory records.
{ "id": "directory_01ECAZ4NV9QMV47GW873HDCX74", "domain": "foo-corp.com", "name": "Foo Corp", "organization_id": "org_01EHZNVPK3SFK441A1RGBFSHRT", "state": "unlinked", "type": "gsuite directory", "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z" }
directory
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.
The states linked
and unlinked
are equivalent to the Directory states active
and inactive
respectively in webhooks.
linked
unlinked
validating
deleting
invalid_credentials
The type of external Directory Provider integrated with.
azure scim v2.0
bamboohr
breathe hr
cezanne hr
generic scim v2.0
gsuite directory
jump cloud scim v2.0
okta scim v2.0
onelogin scim v2.0
people hr
pingfederate scim v2.0
workday
The timestamp when the Directory was created.
The timestamp when the Directory was last updated.
Get the details of an existing directory.
curl https://api.workos.com/directories/directory_01ECAZ4NV9QMV47GW873HDCX74 \ --header "Authorization: Bearer sk_example_123456789"
{ "id": "directory_01ECAZ4NV9QMV47GW873HDCX74", "domain": "foo-corp.com", "name": "Foo Corp", "organization_id": "org_01EHZNVPK3SFK441A1RGBFSHRT", "state": "unlinked", "type": "gsuite directory", "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z" }
Get a list of all of your existing directories matching the criteria specified.
curl https://api.workos.com/directories?search=WorkOS \ --header "Authorization: Bearer sk_example_123456789"
{ "data": [ { "id": "directory_01ECAZ4NV9QMV47GW873HDCX74", "domain": "foo-corp.com", "name": "Foo Corp", "organization_id": "org_01EHZNVPK3SFK441A1RGBFSHRT", "object": "directory", "state": "unlinked", "type": "gsuite directory", "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:08:33.155Z" }, { "id": "directory_01E8CS3GSBEBZ1F1CZAEE3KHDG", "domain": "foo-corp.com", "external_key": "r3NDlInUnAe6i4wG", "name": "Foo Corp", "organization_id": "org_01EHZNVPK3SFK441A1RGBFPANT", "object": "directory", "state": "linked", "type": "okta scim v2.0", "created_at": "2021-06-25T19:09:33.155Z", "updated_at": "2021-06-25T19:10:33.155Z" } ], "list_metadata": { "after": "directory_01E1JJS84MFPPQ3G655FHTKX6Z", "before": "directory_01E1JJS84MFPPQ3G655FHTKX6Z" } }
GET
/directories
Parameters
Searchable text to match against Directory names.
Filter Directories by their associated organization.
Upper limit on the number of objects to return, between 1
and 100
. The default value is 10
.
An object ID that defines your place in the list. When the ID is not present, you are at the end of the list.
For example, if you make a list request and receive 100 objects, ending with "obj_123"
, your subsequent call can include before="obj_123"
to fetch a new batch of objects before "obj_123"
.
An object ID that defines your place in the list. When the ID is not present, you are at the end of the list.
For example, if you make a list request and receive 100 objects, ending with "obj_123"
, your subsequent call can include after="obj_123"
to fetch a new batch of objects after "obj_123"
.
Order the results by the creation time. Supported values are "asc"
and "desc"
for showing older and newer records first respectively. Default order is descending.
Returns
object
Array of Directories ordered by creation time.
An object ID that defines your place in the list. When the ID is not present, you are at the end of the list.
For example, if you make a list request and receive 100 objects, ending with "obj_123"
, your subsequent call can include after="obj_123"
to fetch a new batch of objects after "obj_123"
.
An object ID that defines your place in the list. When the ID is not present, you are at the end of the list.
For example, if you make a list request and receive 100 objects, ending with "obj_123"
, your subsequent call can include before="obj_123"
to fetch a new batch of objects before "obj_123"
.
Delete an existing directory.
curl --request DELETE \ --url https://api.workos.com/directories/directory_01ECAZ4NV9QMV47GW873HDCX74 \ --header "Authorization: Bearer sk_example_123456789"
DELETE
/directories /:id
Parameters
Unique identifier for the Directory.
A Directory User represents an active organization user.
Developers can receive Webhooks as employees are added, updated or removed, allowing for provisioning and de-provisioning Users within an application.
The data stored for employees vary per directory provider and may include attributes such as photo URLs, pay groups, supervisors, etc. Where available, the WorkOS API will provide the additional data in the raw_attributes
field when fetching Directory User records.
{ "id": "directory_user_01E1JG7J09H96KYP8HM9B0G5SJ", "idp_id": "2836", "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74", "organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y", "first_name": "Marcelina", "last_name": "Davis", "job_title": "Software Engineer", "emails": [ { "primary": true, "type": "work", "value": "marcelina@example.com" } ], "username": "marcelina@example.com", "groups": [ { "id": "directory_group_01E64QTDNS0EGJ0FMCVY9BWGZT", "name": "Engineering", "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z", "raw_attributes": {} } ], "state": "active", "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z", "custom_attributes": { "department": "Engineering" }, "raw_attributes": {} }
directory_user
Unique identifier for the Directory User.
Unique identifier for the user, assigned by the Directory Provider. Different Directory Providers use different ID formats.
One possible use case for idp_id
is associating the Directory User with their SSO Profile.
The identifier of the Directory the Directory User belongs to.
The identifier for the Organization in which the Directory resides.
The first name of the user.
The last name of the user.
The job title of the user.
The type of the email account, e.g. "work"
or "personal"
.
The email address of the user.
Whether this is the primary email of the user.
The username of the user.
The groups that the user is a member of.
The state of the user.
active
inactive
An object containing the custom attribute mapping for the Directory Provider.
An object containing the data returned from the Directory Provider.
The timestamp when the Directory User was created.
The timestamp when the Directory User was last updated.
Get the details of an existing Directory User.
curl https://api.workos.com/directory_users/directory_user_01E1JG7J09H96KYP8HM9B0G5SJ \ --header "Authorization: Bearer sk_example_123456789"
{ "id": "directory_user_01E1JG7J09H96KYP8HM9B0G5SJ", "idp_id": "2836", "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74", "organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y", "first_name": "Marcelina", "last_name": "Davis", "job_title": "Software Engineer", "emails": [ { "primary": true, "type": "work", "value": "marcelina@example.com" } ], "username": "marcelina@example.com", "groups": [ { "id": "directory_group_01E64QTDNS0EGJ0FMCVY9BWGZT", "name": "Engineering", "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z", "raw_attributes": {} } ], "state": "active", "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z", "custom_attributes": { "department": "Engineering" }, "raw_attributes": {} }
Get a list of all of existing Directory Users matching the criteria specified.
curl https://api.workos.com/directory_users?directory=directory_01ECAZ4NV9QMV47GW873HDCX74 \ --header "Authorization: Bearer sk_example_123456789"
{ "data": [ { "id": "directory_user_01E1JJHG3BFJ3FNRRHSFWEBNCS", "idp_id": "1902", "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74", "organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y", "emails": [ { "primary": true, "type": "work", "value": "jan@example.com" } ], "first_name": "Jan", "last_name": "Brown", "job_title": "Software Engineer", "username": "jan@example.com", "groups": [ { "id": "directory_group_01E64QTDNS0EGJ0FMCVY9BWGZT", "name": "Engineering", "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z" } ], "state": "active", "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z", "custom_attributes": { "department": "Engineering" } }, { "id": "directory_user_01E1JJHG10ANRA2V6PAX3GD7TE", "idp_id": "8953", "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74", "organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y", "emails": [ { "primary": true, "type": "work", "value": "rosalinda@example.com" } ], "first_name": "Rosalinda", "last_name": "Swift", "job_title": "Software Engineer", "username": "rosalinda@example.com", "groups": [ { "id": "directory_group_01E64QTDNS0EGJ0FMCVY9BWGZT", "name": "Engineering", "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z" } ], "state": "active", "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z", "custom_attributes": { "department": "Engineering" } } ], "object": "list", "list_metadata": { "after": "directory_user_01E4RH82CC8QAP8JTRCTNDSS4C", "before": "directory_user_01E4RH828021B9ZZB8KH8E2Z1W" } }
GET
/directory_user
Parameters
Unique identifier of the WorkOS Directory.
This value can be obtained from the WorkOS dashboard or from the WorkOS API.
Unique identifier of the WorkOS Directory Group.
This value can be obtained from the WorkOS API.
Upper limit on the number of objects to return, between 1
and 100
. The default value is 10
.
An object ID that defines your place in the list. When the ID is not present, you are at the end of the list.
For example, if you make a list request and receive 100 objects, ending with "obj_123"
, your subsequent call can include before="obj_123"
to fetch a new batch of objects before "obj_123"
.
An object ID that defines your place in the list. When the ID is not present, you are at the end of the list.
For example, if you make a list request and receive 100 objects, ending with "obj_123"
, your subsequent call can include after="obj_123"
to fetch a new batch of objects after "obj_123"
.
Order the results by the creation time. Supported values are "asc"
and "desc"
for showing older and newer records first respectively. Default order is descending.
Returns
object
Array of Directory Users ordered by creation time.
Since these can be bulk processed (ex. 10 updates were batched process), there is a secondary sort on the identifier, i.e. id
.
An object ID that defines your place in the list. When the ID is not present, you are at the end of the list.
For example, if you make a list request and receive 100 objects, ending with "obj_123"
, your subsequent call can include after="obj_123"
to fetch a new batch of objects after "obj_123"
.
An object ID that defines your place in the list. When the ID is not present, you are at the end of the list.
For example, if you make a list request and receive 100 objects, ending with "obj_123"
, your subsequent call can include before="obj_123"
to fetch a new batch of objects before "obj_123"
.
A directory group represents an organizational unit of users in a directory provider.
{ "id": "directory_group_01E1JJS84MFPPQ3G655FHTKX6Z", "idp_id": "02grqrue4294w24", "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74", "organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y", "name": "Developers", "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z", "raw_attributes": {} }
directory_group
Unique identifier for the Directory Group.
Unique identifier for the group, assigned by the Directory Provider. Different Directory Providers use different ID formats.
The identifier of the Directory the Directory Group belongs to.
The identifier for the Organization in which the Directory resides.
The name of the Directory Group.
The timestamp when the Directory Group was created.
The timestamp when the Directory Group was last updated.
An object containing the data returned from the Directory Provider.
Get the details of an existing Directory Group.
curl https://api.workos.com/directory_groups/directory_group_01E1JJS84MFPPQ3G655FHTKX6Z \ --header "Authorization: Bearer sk_example_123456789"
{ "id": "directory_group_01E1JJS84MFPPQ3G655FHTKX6Z", "idp_id": "02grqrue4294w24", "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74", "organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y", "name": "Developers", "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z", "raw_attributes": {} }
GET
/directory_groups /:id
Parameters
Unique identifier for the Directory Group.
Returns
Get a list of all of existing directory groups matching the criteria specified.
curl https://api.workos.com/directory_groups?directory=directory_01ECAZ4NV9QMV47GW873HDCX74 \ --header "Authorization: Bearer sk_example_123456789"
{ "data": [ { "id": "directory_group_01E1JJS84MFPPQ3G655FHTKX6Z", "idp_id": "02grqrue4294w24", "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74", "organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y", "name": "Developers", "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z", "raw_attributes": {} } ], "list_metadata": { "after": "directory_group_01E1JJS84MFPPQ3G655FHTKX6Z", "before": "directory_group_01E1JJS84MFPPQ3G655FHTKX6Z" } }
GET
/directory_groups
Parameters
Unique identifier of the WorkOS Directory.
This value can be obtained from the WorkOS dashboard or from the WorkOS API.
Unique identifier of the WorkOS Directory User.
This value can be obtained from the WorkOS API.
Upper limit on the number of objects to return, between 1
and 100
. The default value is 10
.
An object ID that defines your place in the list. When the ID is not present, you are at the end of the list.
For example, if you make a list request and receive 100 objects, ending with "obj_123"
, your subsequent call can include before="obj_123"
to fetch a new batch of objects before "obj_123"
.
An object ID that defines your place in the list. When the ID is not present, you are at the end of the list.
For example, if you make a list request and receive 100 objects, ending with "obj_123"
, your subsequent call can include after="obj_123"
to fetch a new batch of objects after "obj_123"
.
Order the results by the creation time. Supported values are "asc"
and "desc"
for showing older and newer records first respectively. Default order is descending.
Returns
object
Array of Directory Groups ordered by creation time.
An object ID that defines your place in the list. When the ID is not present, you are at the end of the list.
For example, if you make a list request and receive 100 objects, ending with "obj_123"
, your subsequent call can include after="obj_123"
to fetch a new batch of objects after "obj_123"
.
The Admin Portal is a standalone application where your users can configure and manage WorkOS resources such as Connections and Directories that are scoped to their Organization.
A Portal Link is a temporary endpoint to initiate an Admin Portal session. It expires five minutes after issuance.
https://setup.workos.com?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Generate a Portal Link scoped to an Organization.
curl --request POST \ --url https://api.workos.com/portal/generate_link \ --header "Authorization: Bearer sk_example_123456789" \ -d organization="org_01EHZNVPK3SFK441A1RGBFSHRT" \ -d intent="sso"
{ "link": "https://setup.workos.com?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }
POST
/portal /generate_link
Parameters
An Organization identifier.
The intent of the Admin Portal.
sso
- Launch Admin Portal for creating SSO connectionsdsync
- Launch Admin Portal for creating Directory Sync connectionsaudit_logs
- Launch Admin Portal for viewing Audit Logslog_streams
- Launch Admin Portal for creating Log Streamsdomain_verification
- Launch Admin Portal for Domain VerificationThe URL to go to when an admin clicks on your logo in the Admin Portal. If not specified, the return URL configured on the Redirects page will be used.
The URL to redirect the admin to when they finish setup. If not specified, the success URL configured on the Redirects page will be used.
Returns
object
An ephemeral link to initiate the Admin Portal.
Audit Logs are a collection of events that contain information relevant to notable actions taken by users in your application. Every event in the collection contains details regarding what kind of action was taken (action
), who performed the action (actor
), what resources were affected by the action (targets
), and additional details of when and where the action took place.
Emits an Audit Log Event.
curl --request POST \ --url https://api.workos.com/audit_logs/events \ --header "Authorization: Bearer sk_example_123456789" \ --header "Content-Type: application/json" \ --header "Idempotency-Key: 884793cd-bef4-46cf-8790-e3d4957a09ce" \ -d @- <<BODY { "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY", "event": { "action": "user.signed_in", "occurred_at": "2022-09-02T16:35:39.317Z", "version": 1, "actor": { "type": "user", "id": "user_TF4C5938", "metadata": { "role": "admin" } }, "targets": [ { "type": "user", "id": "user_98432YHF", "name": "Jon Smith" }, { "type": "team", "id": "team_J8YASKA2", "metadata": { "owner": "user_01GBTCQ2" } } ], "context": { "location": "123.123.123.123", "user_agent": "Chrome/104.0.0.0" }, "metadata": { "extra": "data" } } } BODY
POST
/audit_logs /events
Parameters
The unique ID of the Organization.
Identifier of what happened
ISO-8601 value of when the action occurred
What schema version the event is associated with
Actor type
Actor identifier
Optional actor name
Additional data that should be associated with the event or entity. There is a limit of 50 keys. Key names can be up to 40 characters long, and values can be up to 500 characters long.
Target type
Target identifier
Optional target name
Additional data that should be associated with the event or entity. There is a limit of 50 keys. Key names can be up to 40 characters long, and values can be up to 500 characters long.
IP Address or some other geolocation identifier
User agent string
Additional data that should be associated with the event or entity. There is a limit of 50 keys. Key names can be up to 40 characters long, and values can be up to 500 characters long.
Creates a new Audit Log schema used to validate the payload of incoming Audit Log Events. If the :action
does not exist, it will also be created.
curl --request POST \ --url https://api.workos.com/audit_logs/actions/user.viewed_invoice/schemas \ --header "Authorization: Bearer sk_example_123456789" \ --header "Content-Type: application/json" \ -d @- <<BODY { "actor": { "metadata": { "type": "object", "properties": { "role": { "type": "string" } } } }, "targets": [ { "type": "invoice", "metadata": { "type": "object", "properties": { "status": { "type": "string" } } } } ], "metadata": { "type": "object", "properties": { "transactionId": { "type": "string" } } } } BODY
POST
/audit_logs /actions /:name /schemas
Parameters
JSON schema for Actor metadata
Actor type
Optional JSON schema for target metadata
Optional JSON schema for event metadata
Get a list of all schemas for the Audit Logs action identified by :name
.
curl https://api.workos.com/audit_logs/actions/user.viewed_invoice/schemas \ --header "Authorization: Bearer sk_example_123456789"
{ "object": "list", "data": [ { "version": 1, "actor": { "metadata": { "type": "object", "properties": { "role": { "type": "string" } } } }, "targets": [ { "type": "invoice", "metadata": { "type": "object", "properties": { "status": { "type": "string" } } } } ], "metadata": { "type": "object", "properties": { "transactionId": { "type": "string" } } }, "updated_at": "2021-06-25T19:07:33.155Z" } ], "list_metadata": { "before": null, "after": null } }
GET
/audit_logs /actions /:name /schemas
Parameters
Upper limit on the number of objects to return, between 1
and 100
. The default value is 10
.
An object ID that defines your place in the list. When the ID is not present, you are at the end of the list.
For example, if you make a list request and receive 100 objects, ending with "obj_123"
, your subsequent call can include before="obj_123"
to fetch a new batch of objects before "obj_123"
.
An object ID that defines your place in the list. When the ID is not present, you are at the end of the list.
For example, if you make a list request and receive 100 objects, ending with "obj_123"
, your subsequent call can include after="obj_123"
to fetch a new batch of objects after "obj_123"
.
Order the results by the creation time. Supported values are "asc"
and "desc"
for showing older and newer records first respectively. Default order is descending.
Returns
object
Array of Audit Log schemas.
An object ID that defines your place in the list. When the ID is not present, you are at the end of the list.
For example, if you make a list request and receive 100 objects, ending with "obj_123"
, your subsequent call can include before="obj_123"
to fetch a new batch of objects before "obj_123"
.
An object ID that defines your place in the list. When the ID is not present, you are at the end of the list.
For example, if you make a list request and receive 100 objects, ending with "obj_123"
, your subsequent call can include after="obj_123"
to fetch a new batch of objects after "obj_123"
.
Get a list of all Audit Log actions in the current environment.
curl https://api.workos.com/audit_logs/actions \ --header "Authorization: Bearer sk_example_123456789"
{ "object": "list", "data": [ { "object": "audit_log_action", "name": "user.viewed_invoice", "schema": { "object": "audit_log_schema", "version": 1, "actor": { "metadata": { "type": "object", "properties": { "role": { "type": "string" } } } }, "targets": [ { "type": "invoice", "metadata": { "type": "object", "properties": { "status": { "type": "string" } } } } ], "metadata": { "type": "object", "properties": { "transactionId": { "type": "string" } } }, "updated_at": "2021-06-25T19:07:33.155Z" }, "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z" } ], "list_metadata": { "before": null, "after": null } }
GET
/audit_logs /actions /:name /actions
Parameters
Upper limit on the number of objects to return, between 1
and 100
. The default value is 10
.
An object ID that defines your place in the list. When the ID is not present, you are at the end of the list.
For example, if you make a list request and receive 100 objects, ending with "obj_123"
, your subsequent call can include before="obj_123"
to fetch a new batch of objects before "obj_123"
.
An object ID that defines your place in the list. When the ID is not present, you are at the end of the list.
For example, if you make a list request and receive 100 objects, ending with "obj_123"
, your subsequent call can include after="obj_123"
to fetch a new batch of objects after "obj_123"
.
Order the results by the creation time. Supported values are "asc"
and "desc"
for showing older and newer records first respectively. Default order is descending.
Returns
object
Array of Audit Log actions.
An object ID that defines your place in the list. When the ID is not present, you are at the end of the list.
For example, if you make a list request and receive 100 objects, ending with "obj_123"
, your subsequent call can include before="obj_123"
to fetch a new batch of objects before "obj_123"
.
An object ID that defines your place in the list. When the ID is not present, you are at the end of the list.
For example, if you make a list request and receive 100 objects, ending with "obj_123"
, your subsequent call can include after="obj_123"
to fetch a new batch of objects after "obj_123"
.
An object representing an Audit Log Export.
{ "object": "audit_log_export", "id": "audit_log_export_01GBZK5MP7TD1YCFQHFR22180V", "state": "ready", "url": "https://exports.audit-logs.com/audit-log-exports/export.csv", "created_at": "2022-09-02T17:14:57.094Z", "updated_at": "2022-09-02T17:14:57.094Z" }
audit_log_export
Distinguishes the Audit Log Export object.
The unique ID of the Audit Log Export.
The timestamp when the Audit Log Export was created.
The timestamp when the Audit Log Export was last updated.
The state of the export. Possible values:
pending
ready
error
.A URL to the CSV file. Only defined when the Audit Log Export is ready.
Create an Audit Log Export.
curl --request POST \ --url https://api.workos.com/audit_logs/exports \ --header "Authorization: Bearer sk_example_123456789" \ -d organization_id="org_01EHZNVPK3SFK441A1RGBFSHRT" \ -d range_start="2022-07-02T18:09:06.996Z" \ -d range_end="2022-09-02T18:09:06.996Z" \ -d 'actions[]=user.signed_in' \ -d 'actors[]=Jon Smith' \ -d 'targets[]=team'
{ "object": "audit_log_export", "id": "audit_log_export_01GBZK5MP7TD1YCFQHFR22180V", "state": "ready", "url": "https://exports.audit-logs.com/audit-log-exports/export.csv", "created_at": "2022-09-02T17:14:57.094Z", "updated_at": "2022-09-02T17:14:57.094Z" }
POST
/audit_logs /exports
Parameters
The unique ID of the Organization.
ISO-8601 value for start of the export range.
ISO-8601 value for end of the export range.
List of actions to filter against.
List of actor names to filter against.
List of target types to filter against.
Returns
Get an Audit Log Export.
curl https://api.workos.com/audit_logs/exports/audit_log_export_01GBZK5MP7TD1YCFQHFR22180V \ --header "Authorization: Bearer sk_example_123456789"
{ "object": "audit_log_export", "id": "audit_log_export_01GBZK5MP7TD1YCFQHFR22180V", "state": "ready", "url": "https://exports.audit-logs.com/audit-log-exports/export.csv", "created_at": "2022-09-02T17:14:57.094Z", "updated_at": "2022-09-02T17:14:57.094Z" }
The URL will expire after 10 minutes. If the export is needed again at a later time, refetching the export will regenerate the URL.
Get the configured event retention period for the given Organization.
curl https://api.workos.com/organizations/org_01EHZNVPK3SFK441A1RGBFSHRT/audit_logs_retention \ --header "Authorization: Bearer sk_example_123456789"
{ "retention_period_in_days": 30 }
GET
/organizations /:id /audit_logs_retention
Parameters
Unique identifier of the Organization.
Returns
object
The number of days Audit Log events will be retained.
Set the event retention period for the given Organization.
curl --request PUT \ --url https://api.workos.com/organizations/org_01EHZNVPK3SFK441A1RGBFSHRT/audit_logs_retention \ --header "Authorization: Bearer sk_example_123456789" \ --header "Content-Type: application/json" \ -d '{ "retention_period_in_days": 30 }'
{ "retention_period_in_days": 30 }
PUT
/organizations /:id /audit_logs_retention
Parameters
Unique identifier of the Organization.
The number of days Audit Log events will be retained. Valid values are 30
and 365
.
Returns
object
The number of days Audit Log events will be retained.
An organization domain represents an organization's domain. Domains can be verified to assert that an organization owns the configured domain which is accomplished through DNS TXT record verification.
To automatically respond to changes in the organization domains, use Domain Verification events.
const organization_domain = { object: 'organization_domain', id: 'org_domain_01HE8GSH9BC1T08J2A9K6TDERK', organizationId: 'org_01HE8GSH8FQPASKSY27THRKRBP', domain: 'your-domain.net', state: 'verified', verificationStrategy: 'dns', verificationToken: 'm5Oztg3jdK4NJLgs8uIlIprMw', };
interface OrganizationDomain
Distinguishes the organization domain object.
Unique identifier of the organization domain.
ID of the parent Organization.
Domain for the organization domain.
Verification state of the domain.
Strategy used to verify the domain
validation token to be used in DNS TXT record.
Get the details of an existing organization.
curl --request GET \ --url https://api.workos.com/organization_domains/org_domain_01HEJXJSTVEDT7T58BM70FMFET \ --header "Authorization: Bearer sk_example_123456789" \
{ "object": "organization_domain", "id": "org_domain_01HEJXJSTVEDT7T58BM70FMFET", "organization_id": "org_01EHT88Z8J8795GZNQ4ZP1J81T", "domain": "foo2.com", "state": "pending", "verification_strategy": "dns", "verification_token": "aW5HQ8Sgps1y3LQyrShsFRo3F" }
GET
/organization_domains /:id
Parameters
Unique identifier of the organization domain.
Returns
Creates a new Organization Domain.
curl --request POST \ --url https://api.workos.com/organization_domains \ --header "Authorization: Bearer sk_example_123456789" \ -d organization_id="org_01EHT88Z8J8795GZNQ4ZP1J81T" \ -d 'domain="foo-corp.com"'
{ "object": "organization_domain", "id": "org_domain_01HEJXJSTVEDT7T58BM70FMFET", "organization_id": "org_01EHT88Z8J8795GZNQ4ZP1J81T", "domain": "foo2.com", "state": "pending", "verification_strategy": "dns", "verification_token": "aW5HQ8Sgps1y3LQyrShsFRo3F" }
POST
/organization-domains
Parameters
ID of the parent Organization.
Domain for the organization domain.
Returns
Initiates verification process for an Organization Domain.
curl --request POST \ --url https://api.workos.com/organization_domains/org_domain_01HEJXJSTVEDT7T58BM70FMFET/verify \ --header "Authorization: Bearer sk_example_123456789" \
{ "object": "organization_domain", "id": "org_domain_01HEJXJSTVEDT7T58BM70FMFET", "organization_id": "org_01EHT88Z8J8795GZNQ4ZP1J81T", "domain": "foo2.com", "state": "pending", "verification_strategy": "dns", "verification_token": "oNKzjqppp347rDBgLA5dTo8uA" }
POST
/organization-domains /:id /verify
Parameters
Unique identifier of the organization domain.
Returns
An object representing an Authentication Factor.
{ "object": "authentication_factor", "id": "auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ", "created_at": "2022-02-15T15:14:19.392Z", "updated_at": "2022-02-15T15:14:19.392Z", "type": "totp", "totp": { "qr_code": "data:image/png;base64,{base64EncodedPng}", "secret": "NAGCCFS3EYRB422HNAKAKY3XDUORMSRF", "uri": "otpauth://totp/FooCorp:alan.turing@example.com?secret=NAGCCFS3EYRB422HNAKAKY3XDUORMSRF&issuer=FooCorp" } }
authentication_factor
Distinguishes the authentication factor object.
The unique ID of the factor.
The timestamp when the factor was created.
The timestamp when the factor was last updated.
The type of the factor to enroll. The only available option is TOTP.
Your application or company name displayed in the user’s authenticator app. Defaults to your WorkOS team name.
The user’s account name displayed in their authenticator app. Defaults to the user’s email.
Base64 encoded image containing scannable QR code.
TOTP secret that can be manually entered into some authenticator apps in place of scanning a QR code.
The otpauth
URI that is encoded by the provided qr_code
.
The ID of the user.
An object representing a Challenge of an Authentication Factor.
{ "object": "authentication_challenge", "id": "auth_challenge_01FVYZWQTZQ5VB6BC5MPG2EYC5", "created_at": "2022-02-15T15:26:53.274Z", "updated_at": "2022-02-15T15:26:53.274Z", "expires_at": "2022-02-15T15:36:53.279Z", "authentication_factor_id": "auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ" }
authentication_challenge
Distinguishes the authentication challenge object.
The unique ID of the authentication challenge.
The timestamp when the challenge was created.
The timestamp when the challenge was last updated.
The timestamp when the challenge will expire. Does not apply to TOTP factors.
The unique ID of the authentication factor the challenge belongs to.
Enrolls an Authentication Factor to be used as an additional factor of authentication. The returned ID should be used to create an authentication Challenge.
curl --request POST \ --url https://api.workos.com/auth/factors/enroll \ --header "Authorization: Bearer sk_example_123456789" \ -d type="totp" \ -d totp_issuer="Foo Corp" \ -d totp_user="alan.turing@example.com"
{ "object": "authentication_factor", "id": "auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ", "created_at": "2022-02-15T15:14:19.392Z", "updated_at": "2022-02-15T15:14:19.392Z", "type": "totp", "totp": { "qr_code": "data:image/png;base64,{base64EncodedPng}", "secret": "NAGCCFS3EYRB422HNAKAKY3XDUORMSRF", "uri": "otpauth://totp/FooCorp:alan.turing@example.com?secret=NAGCCFS3EYRB422HNAKAKY3XDUORMSRF&issuer=FooCorp" } }
POST
/auth /factors /enroll
Parameters
The type of factor you wish to enroll.
totp
sms
An identifier for the organization issuing the challenge. Should be the name of your application or company. Required when type is totp
.
An identifier for the user. Used by authenticator apps to label connections. Required when type is totp
.
A valid phone number for an SMS-enabled device. Required when type is sms
.
Returns
Creates a Challenge for an Authentication Factor.
curl --request POST \ --url https://api.workos.com/auth/factors/auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ/challenge \ --header "Authorization: Bearer sk_example_123456789"
{ "object": "authentication_challenge", "id": "auth_challenge_01FVYZWQTZQ5VB6BC5MPG2EYC5", "created_at": "2022-02-15T15:26:53.274Z", "updated_at": "2022-02-15T15:26:53.274Z", "expires_at": "2022-02-15T15:36:53.279Z", "authentication_factor_id": "auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ" }
POST
/auth /factors /:id /challenge
Parameters
The unique ID of the Authentication Factor to be challenged.
Optional template for SMS messages. Only applicable for sms
Factors. Use the {{code}}
token to inject the one-time code into the message. E.g., Your Foo Corp one-time code is {{code}}.
Returns
Verify Authentication Challenge.
curl --request POST \ --url https://api.workos.com/auth/challenges/auth_challenge_01FVYZWQTZQ5VB6BC5MPG2EYC5/verify \ --header "Authorization: Bearer sk_example_123456789" \ -d code="123456"
{ "challenge": { "object": "authentication_challenge", "id": "auth_challenge_01FVYZWQTZQ5VB6BC5MPG2EYC5", "created_at": "2022-02-15T15:26:53.274Z", "updated_at": "2022-02-15T15:26:53.274Z", "expires_at": "2022-02-15T15:36:53.279Z", "authentication_factor_id": "auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ" }, "valid": true }
POST
/auth /challenges /:id /verify
Parameters
The unique ID of the authentication Challenge.
The 6 digit code to be verified.
Returns
object
The relevant Authentication Challenge.
Indicates whether the code was correct.
Gets an Authentication Factor.
curl https://api.workos.com/auth/factors/auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ \ --header "Authorization: Bearer sk_example_123456789"
{ "object": "authentication_factor", "id": "auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ", "created_at": "2022-02-15T15:14:19.392Z", "updated_at": "2022-02-15T15:14:19.392Z", "type": "totp", "totp": { "qr_code": "data:image/png;base64,{base64EncodedPng}", "secret": "NAGCCFS3EYRB422HNAKAKY3XDUORMSRF", "uri": "otpauth://totp/FooCorp:alan.turing@example.com?secret=NAGCCFS3EYRB422HNAKAKY3XDUORMSRF&issuer=FooCorp" } }
Deletes an Authentication Factor.
curl --request DELETE \ --url https://api.workos.com/auth/factors/auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ \ --header "Authorization: Bearer sk_example_123456789"
DELETE
/auth /factors /:id
Parameters
The unique ID of the factor.
Deprecated API: Magic Link has been replaced by the User Management Magic Auth API.
The Magic Link API can be used to add Passwordless Authentication to your app.
An object representing a passwordless authentication session.
{ "object": "passwordless_session", "id": "passwordless_session_01EHDAK2BFGWCSZXP9HGZ3VK8C", "email": "marcelina@example.com", "expires_at": "2020-08-13T05:50:00.000Z", "link": "https://auth.workos.com/passwordless/4TeRexuejWCKs9rrFOIuLRYEr/confirm" }
passwordless_session
Distinguishes the Paswordless Session object.
The unique ID of the session.
The email address of the user for the session.
The ISO-8601 datetime at which the session expires.
The link for the user to authenticate with. You can use this link to send a custom email to the user, or send an email using Email a Magic Link to the user.
Once a user has authenticated with the link, WorkOS issues a redirect to the Environment’s default redirect URI, with a code
parameter and, if provided during session creation, a state
parameter.
Code can then be exchanged for an access token and user Profile. To perform this exchange, the Developer should make a POST request to the /sso/token
endpoint.
If the link has expired, WorkOS will issue a redirect with an error
query parameter and value of access_denied
.
Create a Passwordless Session for a Magic Link Connection.
curl --request POST \ --url https://api.workos.com/passwordless/sessions \ --header "Authorization: Bearer sk_example_123456789" \ -d email="marcelina@example.com" \ -d type="MagicLink"
{ "object": "passwordless_session", "id": "passwordless_session_01EHDAK2BFGWCSZXP9HGZ3VK8C", "email": "marcelina@example.com", "expires_at": "2020-08-13T05:50:00.000Z", "link": "https://auth.workos.com/passwordless/4TeRexuejWCKs9rrFOIuLRYEr/confirm" }
POST
/passwordless /sessions
Parameters
The email of the user to authenticate.
The type of Passwordless Session to create. Currently, the only supported value is MagicLink
.
Optional parameter that a developer can choose to include in their authorization URL. If included, it will override the default Redirect URI set in the dashboard. This is the location your user will be redirected to once the session has been completed successfully.
The number of seconds the Passwordless Session should live before expiring.
This value must be between 900
(15 minutes) and 86400
(24 hours), inclusive.
Optional parameter that a developer can choose to include in their authorization URL. If included, then the redirect URI received from WorkOS will contain the exact state
that was passed in the authorization URL.
The state
parameter can be used to encode arbitrary information to help restore application state between redirects.
Returns
Email a user the Magic Link confirmation URL.
curl --request POST \ --url https://api.workos.com/passwordless/sessions/passwordless_session_01EG1BHJMVYMFBQYZTTC0N73CR/send \ --header "Authorization: Bearer sk_example_123456789"
{ "success": true }
POST
Sends email/passwordless /sessions /:id /send
Parameters
The unique identifier of the Passwordless Session to send an email for.
Returns
object
A confirmation that the Magic Link was sent.