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
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 |
SSO 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" }, "role": { "slug": "member" }, "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
Returns
object
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
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
Returns
object
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" } ] }
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" } ] }
Permanently deletes an organization in the current environment. It cannot be undone.
curl --request DELETE \ --url https://api.workos.com/organizations/org_01EHZNVPK3SFK441A1RGBFSHRT \ --header "Authorization: Bearer sk_example_123456789"
DELETE
/organizations /:id
Parameters
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 SSO frequently asked questions for more details on this behavior.
{ "id": "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A", "object": "organization_domain", "domain": "foo-corp.com" }
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
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
Returns
object
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" }
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" }
Permanently deletes a user in the current environment. It cannot be undone.
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
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
Returns
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 can use state
to encode parameters like originating URL and query parameters. This is useful in a flow where unauthenticated users are automatically redirected to a login page. After successful sign in, users will be routed to your redirect URI callback route. From there you can extract the originating URL from state
and redirect the user to their intended destination.
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
Returns
object
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
Returns
object
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
Returns
object
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
Returns
object
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.
If the email setting for email verification is enabled, WorkOS will automatically send a one-time email verification code to the user’s email address. If the email setting is not enabled, retrieve the email verification code to send the email yourself. 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
Returns
object
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
Returns
object
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
Returns
object
Authenticates a user using an AuthKit session cookie. This method does not make a network call, but simply unseals an existing session cookie and decodes the JWT claims from the access token.
import { AuthenticateWithSessionCookieFailureReason, WorkOS, } from '@workos-inc/node'; const workos = new WorkOS('sk_example_123456789', { // clientId is required to be passed in to use the authenticateWithSessionCookie method clientId: 'client_123456789', }); const { authenticated, ...restOfAuthenticationResponse } = await workos.userManagement.authenticateWithSessionCookie({ sessionData: 'sealed_session_cookie_data', cookiePassword: 'password_previously_used_to_seal_session_cookie', }); if (authenticated) { // User is authenticated and session data can be utilized const { sessionId, organizationId, role, permissions } = restOfAuthenticationResponse; } else { const { reason } = restOfAuthenticationResponse; // Can use AuthenticateWithSessionCookieFailureReason to handle failure reasons if ( reason === AuthenticateWithSessionCookieFailureReason.NO_SESSION_COOKIE_PROVIDED ) { // Redirect the user to the login page } }
{ "authenticated": true, "session_id": "session_01HQSXZGF8FHF7A9ZZFCW4387R", "organization_id": "org_01H945H0YD4F97JN9MATX7BYAG", "role": "member", "permissions": ["posts:read", "posts:write"] }
{ "authenticated": false, "reason": "invalid_session_cookie" }
userManagement .authenticateWithSessionCookie()
Parameters
object
Returns
object
Unseals the provided session data from a user’s session cookie, authenticates with the existing refresh token, and returns the sealed data for the refreshed session.
import { RefreshAndSealSessionDataFailureReason, WorkOS, } from '@workos-inc/node'; const workos = new WorkOS('sk_example_123456789', { // clientId is required to be passed in to use the refreshAndSealSessionData method clientId: 'client_123456789', }); const { authenticated, ...restOfRefreshResponse } = await workos.userManagement.refreshAndSealSessionData({ sessionData: 'sealed_session_cookie_data', cookiePassword: 'password_previously_used_to_seal_session_cookie', }); if (authenticated) { const { sealedSession } = restOfRefreshResponse; // Set the sealed session in a cookie } else { const { reason } = restOfRefreshResponse; // Can use RefreshAndSealSessionDataFailureReason to handle failure reasons if ( reason === RefreshAndSealSessionDataFailureReason.NO_SESSION_COOKIE_PROVIDED ) { // Redirect the user to the login page } }
{ "authenticated": true, "sealed_session": "Fe26.2*1*d7f59d8b9d29c26c44dd3df2b56a7d1d40d4" }
{ "authenticated": false, "reason": "invalid_session_cookie" }
userManagement .refreshAndSealSessionData()
Parameters
object
Returns
object
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
Returns
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", "permissions": ["posts:read", "posts:write"], "sid": "session_01HQSXZGF8FHF7A9ZZFCW4387R", "jti": "01HQSXZXPPFPKMDD32RKTFY6PV", "exp": 1709193857, "iat": 1709193557 }
Access Token JWT
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.
After authenticating and storing the encrypted session as a cookie, retrieving and decrypting the session is made easy via the session helper methods.
Load the session by providing the sealed session and the cookie password.
import { WorkOS } from '@workos-inc/node'; const workos = new WorkOS('sk_example_123456789', { clientId: 'client_123456789', }); const session = await workos.userManagement.loadSealedSession({ sessionData: 'sealed_session_cookie_data', cookiePassword: 'password_previously_used_to_seal_session_cookie', });
userManagement .loadSealedSession()
Parameters
object
Returns
object
Unseals the session data and checks if the session is still valid.
import { WorkOS } from '@workos-inc/node'; const workos = new WorkOS('sk_example_123456789', { clientId: 'client_123456789', }); const session = await workos.userManagement.loadSealedSession({ sessionData: 'sealed_session_cookie_data', cookiePassword: 'password_previously_used_to_seal_session_cookie', }); const { user, authenticated, reason } = await session.authenticate(); if (authenticated) { // User is authenticated and session data can be used const { sessionId, organizationId, role, permissions } = user; } else { if (reason === 'no_session_cookie_provided') { // Redirect the user to the login page } }
session .authenticate()
Returns
object
Refreshes the user’s session with the refresh token.
import { WorkOS } from '@workos-inc/node'; const workos = new WorkOS('sk_example_123456789', { clientId: 'client_123456789', }); const session = await workos.userManagement.loadSealedSession({ sessionData: 'sealed_session_cookie_data', cookiePassword: 'password_previously_used_to_seal_session_cookie', }); const { authenticated, session: newSession, sealedSession, } = await session.refresh(); if (!authenticated) { // Redirect the user to the login page } // Use newSession for further business logic // Set the sealedSession in a cookie
session .refresh()
Parameters
object
Returns
object
End a user’s session. The user’s browser should be redirected to this URL. Functionally similar to Get logout URL but extracts the session ID automatically from the session data.
import { WorkOS } from '@workos-inc/node'; const workos = new WorkOS('sk_example_123456789', { clientId: 'client_123456789', }); const session = await workos.userManagement.loadSealedSession({ sessionData: 'sealed_session_cookie_data', cookiePassword: 'password_previously_used_to_seal_session_cookie', }); const logOutUrl = await session.getLogOutUrl(); // Redirect the user to the log out URL
session .getLogOutUrl()
Returns
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_id": "email_verification_01HYGGEB6FYMWQNWF3XDZG7VV3" }
email_verification_required
When this error occurs and the email setting for email verification is enabled, WorkOS will automatically send a one-time email verification code to the user’s email address and issue a pending authentication token. If the email setting is not enabled, retrieve the email verification code to send the email verification email yourself. 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
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
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
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 a domain policy managing this user. It includes all the possible methods the user can use to authenticate.
{ "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": { "apple_oauth": false, "github_oauth": false, "google_oauth": true, "magic_auth": false, "microsoft_oauth": false, "password": false } }
organization_authentication_methods_required
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" }
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" }
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
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
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",