API reference

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.

API Base URL

 https://api.workos.com

Client libraries

WorkOS offers native SDKs in several popular programming languages. Choose one language below to see our API Reference in your application’s language.

Testing the API

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.

API Keys

WorkOS authenticates your API requests using your account’s API keys. API requests made without authentication or using an incorrect key will return a 401 error. Requests using a valid key but with insufficient permissions will return a 403 error. All API requests must be made over HTTPS. Any requests made over plain HTTP will fail.

Set API Key

 curl https://api.workos.com/directories \
  --header "Authorization: Bearer sk_example_123456789"

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

Secure your API Keys

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

In Staging

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.

In Production

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.

Errors

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

200: Successful request.
400: The request was not acceptable. Check that the parameters were correct.
401: The API key used was invalid.
403: The API key used did not have the correct permissions.
404: The resource was not found.
422: Validation failed for the request. Check that the parameters were correct.
429: Too many requests. Refer to the Rate Limits section.
5xx: Indicates an error with WorkOS servers.

Pagination

Many top-level resources have support for bulk fetches via list API methods. For instance, you can list connections, list directory users, and list directory groups. These list API methods share a common structure, taking at least these 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`

Idempotency

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.

Idempotency Key Example

cURL

 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.

Rate limits

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.

General

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.

Single Sign-On

Name	Path	Limit
Get Authorization URL	/sso/authorize	1,000 requests per 60 seconds per connection

Directory Sync

Name	Path	Limit
Directory Users	/directory_users	4 requests per second per directory

User Management

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

Hosted AuthKit

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

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.

List events

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`

`Returns` `object`

Organization

An Organization is a top-level resource in WorkOS. Each Connection, Directory, and Audit Trail Event belongs to an Organization. An Organization will usually represent one of your customers.

Example Organization

 {
  "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 an 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

`/organizations/:id`

`Parameters`

`Returns`

organization

List Organizations

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`

Create an Organization

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`

`Returns`

organization

Update an Organization

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`

`Returns`

organization

Delete an Organization

Deletes an organization in the current environment.

Request

 curl --request DELETE \
  --url https://api.workos.com/organizations/org_01EHZNVPK3SFK441A1RGBFSHRT \
  --header "Authorization: Bearer sk_example_123456789"

DELETE

`/organizations/:id`

`Parameters`

Organization Domain

An Organization Domain (also known as a User Email Domain) represents an Organization‘s domain.

These domains restrict which email addresses are able to sign in through SAML Connections when allow profiles outside organization is false. This is the default behavior for Organizations. See SSO frequently asked questions for more details on this behavior.

Example Organization Domain

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

`organization_domain`

User Management

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.

User

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.

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"
}

`user`

Get a 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

`/user_management/users/:id`

`Parameters`

`Returns`

user

List users

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 user

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`

`Returns`

user

Update a user

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`

`Returns`

user

Delete a user

Deletes a user in the current environment.

Request

 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`

Authentication

Authenticate a user with a specified authentication method.

Get an authorization URL

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.

Redirect URI

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.

Redirect URI with query parameters

 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 environments

HTTP and localhost are allowed in staging environments

Wildcard characters are not allowed in production environments

PKCE

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

Error codes

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.

Redirect URI with an error code

 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.

Authenticate with code

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`

Authenticate a user with password

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`

Authenticate with Magic Auth

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`

Authenticate with refresh token

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`

Authenticate with an email verification code

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`

Authenticate with a time-based one-time password

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`

Authenticate with organization selection

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.

JavaScript

 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,
    cookiePassword,
  });

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`

Refresh and seal session data

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.

JavaScript

 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,
    cookiePassword,
  });

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`

Session tokens

JWKS URL

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`

Access token

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.

Decoded access token

JSON

 {
  "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`

Refresh token

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.

Authentication errors

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.

Email verification required error

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.

Email verification required error

JSON

 {
  "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"
}

Sends email

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

MFA enrollment error

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.

MFA enrollment error

JSON

 {
  "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.

MFA challenge error

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.

MFA challenge error

JSON

 {
  "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.

Organization selection required error

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.

Organization selection required error

JSON

 {
  "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.

SSO required 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.

SSO required error

JSON

 {
  "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.

Organization authentication required error

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.

Organization authentication required error

JSON

 {
  "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

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.

Example 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 a Magic Auth code

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`

`Returns`

magic_auth

Create a Magic Auth code

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"
}

POSTSends email

`/user_management/magic_auth`

`Parameters`

`Returns`

magic_auth

Multi-Factor Authentication

Enroll users in multi-factor authentication for an additional layer of security. MFA can be enabled via the Authentication page in the WorkOS dashboard.

Authentication factor

Represents an authentication factor.

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`

Authentication challenge

Represents a challenge of an authentication factor.

Authentication 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"
}

`authentication_challenge`

Enroll an authentication factor

Enrolls a user in a new authentication factor.

Request

 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`

`Returns` `object`

List authentication factors

Lists the authentication factors for a user.

Request

 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`

`Returns` `object`

Email verification

Email verification is a security feature that requires users to verify their email address before they can sign in to your application. It is enabled by default.

Users signing with Magic Auth, OAuth, or SSO are automatically verified. For other authentication methods, an email verification flow is required to confirm that the user’s email address belongs to them.

Example email verification

 {
  "id": "email_verification_01HYGGEB6FYMWQNWF3XDZG7VV3",
  "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 an email verification code

Get the details of an existing email verification code that can be used to send an email to a user for verification.

 curl https://api.workos.com/user_management/email_verification/email_verification_01HYGGEB6FYMWQNWF3XDZG7VV3 \
  --header "Authorization: Bearer sk_example_123456789"

 {
  "id": "email_verification_01HYGGEB6FYMWQNWF3XDZG7VV3",
  "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/email_verification/:id`

`Parameters`

`Returns`

email_verification

Password reset

Create a password reset token for a user and reset the user’s password.

Example Password reset

 {
  "id": "password_reset_01HYGDNK5G7FZ4YJFXYXPB5JRW",
  "user_id": "user_01HWWYEH2NPT48X82ZT23K5AX4",
  "email": "marcelina.davis@example.com",
  "password_reset_token": "Z1uX3RbwcIl5fIGJJJCXXisdI",
  "password_reset_url": "https://your-app.com/reset-password?token=Z1uX3RbwcIl5fIGJJJCXXisdI",
  "expires_at": "2021-07-01T19:07:33.155Z",
  "created_at": "2021-06-25T19:07:33.155Z"
}

Get a password reset token

Get the details of an existing password reset token that can be used to reset a user’s password.

 curl https://api.workos.com/user_management/password_reset/password_reset_01HYGDNK5G7FZ4YJFXYXPB5JRW \
  --header "Authorization: Bearer sk_example_123456789"

 {
  "id": "password_reset_01HYGDNK5G7FZ4YJFXYXPB5JRW",
  "user_id": "user_01HWWYEH2NPT48X82ZT23K5AX4",
  "email": "marcelina.davis@example.com",
  "password_reset_token": "Z1uX3RbwcIl5fIGJJJCXXisdI",
  "password_reset_url": "https://your-app.com/reset-password?token=Z1uX3RbwcIl5fIGJJJCXXisdI",
  "expires_at": "2021-07-01T19:07:33.155Z",
  "created_at": "2021-06-25T19:07:33.155Z"
}

GET

`/user_management/password_reset/:id`

`Parameters`

`Returns`

password_reset

Create a password reset token

Creates a one-time token that can be used to reset a user’s password.

 curl --request POST \
  --url https://api.workos.com/user_management/password_reset \
  --header "Authorization: Bearer sk_example_123456789" \
  -d email="marcelina.davis@example.com"

 {
  "id": "password_reset_01HYGDNK5G7FZ4YJFXYXPB5JRW",
  "user_id": "user_01HWWYEH2NPT48X82ZT23K5AX4",
  "email": "marcelina.davis@example.com",
  "password_reset_token": "Z1uX3RbwcIl5fIGJJJCXXisdI",
  "password_reset_url": "https://your-app.com/reset-password?token=Z1uX3RbwcIl5fIGJJJCXXisdI",
  "expires_at": "2021-07-01T19:07:33.155Z",
  "created_at": "2021-06-25T19:07:33.155Z"
}

POSTSends email

`/user_management/password_reset`

`Parameters`

`Returns`

password_reset

Reset the password

Sets a new password using the token query parameter from the link that the user received. Successfully resetting the password will verify a user’s email, if it hasn’t been verified yet.

Request

 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`

`Returns` `object`

Organization membership

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.

Example organization membership

 {
  "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`

Get an organization membership

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`

`Returns`

organization_membership

List organization memberships

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`

`Returns` `object`

Create an organization membership

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`

`Returns`

organization_membership

Update an organization membership

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`

`Returns`

organization_membership

Delete an organization membership

Deletes an existing organization membership.

Request

 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`

Deactivate an organization membership

Deactivates an active organization membership. Emits an organization_membership.updated event upon successful deactivation.

Deactivating an inactive membership is a no-op and does not emit an event.

Deactivating a pending membership returns an error. This membership should be deleted instead.

See the membership management documentation for additional details.

 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`

`Returns`

organization_membership

Reactivate an organization membership

Reactivates an inactive organization membership, retaining the pre-existing role. Emits an organization_membership.updated event upon successful reactivation.

Reactivating an active membership is a no-op and does not emit an event.

Reactivating a pending membership returns an error. The user needs to accept the invitation instead.

See the membership management documentation for additional details.

 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`

`Returns`

organization_membership

Invitation

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.

Example 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://your-app.com/invite?invitation_token=Z1uX3RbwcIl5fIGJJJCXXisdI",
  "organization_id": "org_01E4ZCR3C56J083X43JQXF3JK5",
  "inviter_user_id": "user_01HYGBX8ZGD19949T3BM4FW1C3",
  "created_at": "2021-06-25T19:07:33.155Z",
  "updated_at": "2021-06-25T19:07:33.155Z"
}

Get an invitation

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://your-app.com/invite?invitation_token=Z1uX3RbwcIl5fIGJJJCXXisdI",
  "organization_id": "org_01E4ZCR3C56J083X43JQXF3JK5",
  "inviter_user_id": "user_01HYGBX8ZGD19949T3BM4FW1C3",
  "created_at": "2021-06-25T19:07:33.155Z",
  "updated_at": "2021-06-25T19:07:33.155Z"
}

GET

`/user_management/invitations/:id`

`Parameters`

`Returns`

invitation

Find an invitation by token

Retrieve an existing invitation using the token.

 curl https://api.workos.com/user_management/invitations/by_token/Z1uX3RbwcIl5fIGJJJCXXisdI \
  --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://your-app.com/invite?invitation_token=Z1uX3RbwcIl5fIGJJJCXXisdI",
  "organization_id": "org_01E4ZCR3C56J083X43JQXF3JK5",
  "inviter_user_id": "user_01HYGBX8ZGD19949T3BM4FW1C3",
  "created_at": "2021-06-25T19:07:33.155Z",
  "updated_at": "2021-06-25T19:07:33.155Z"
}

GET

`/user_management/invitations/by_token/:token`

`Parameters`

`Returns`

invitation

List invitations

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://your-app.com/invite?invitation_token=Z1uX3RbwcIl5fIGJJJCXXisdI",
      "organization_id": "org_01E4ZCR3C56J083X43JQXF3JK5",
      "inviter_user_id": "user_01HYGBX8ZGD19949T3BM4FW1C3",
      "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`

`Returns` `object`

Send an invitation

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://your-app.com/invite?invitation_token=Z1uX3RbwcIl5fIGJJJCXXisdI",
  "organization_id": "org_01E4ZCR3C56J083X43JQXF3JK5",
  "inviter_user_id": "user_01HYGBX8ZGD19949T3BM4FW1C3",
  "created_at": "2021-06-25T19:07:33.155Z",
  "updated_at": "2021-06-25T19:07:33.155Z"
}

POSTSends email

`/user_management/invitations`

`Parameters`

`Returns`

invitation

Revoke an invitation

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://your-app.com/invite?invitation_token=Z1uX3RbwcIl5fIGJJJCXXisdI",
  "organization_id": "org_01E4ZCR3C56J083X43JQXF3JK5",
  "inviter_user_id": "user_01HYGBX8ZGD19949T3BM4FW1C3",
  "created_at": "2021-06-25T19:07:33.155Z",
  "updated_at": "2021-06-25T19:07:33.155Z"
}

POST

`/user_management/invitations/:id/revoke`

`Parameters`

`Returns`

invitation

Logout

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`

`Returns`

Single Sign-On

The Single Sign-On API has been modeled to meet the OAuth 2.0 framework specification. As a result, authentication flows constructed using the Single Sign-On API replicate the OAuth 2.0 protocol flow.

To automatically respond to changes in your SSO connections, use the Connection events.

Get an authorization URL

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`

`Returns`

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.

Redirect URI

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.

Redirect URI with query parameters

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

Redirect URIs follow stricter requirements in production environments:

HTTPS protocol is required in production environments

HTTP and localhost are allowed in staging environments

Wildcard characters are not allowed in production environments

Error codes

Redirect URI with an error code

 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, add the missing domain to the organization’s Domains. You can read about other options in the SSO Domains guide.
`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.

Profile

A Profile is an object that represents an authenticated user. The Profile object contains information relevant to a user in the form of normalized and raw attributes.

After receiving the Profile for an authenticated user, use the Profile object attributes to persist relevant data to your application’s user model for the specific, authenticated user.

No Profile attributes can be returned other than the normalized attributes listed below, and the raw attributes returned by an Identity Provider.

Example 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": {}
}

`profile`

Get a Profile and Token

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`

`Returns` `object`

Get a User Profile

Exchange an access token for a user’s Profile. Because this profile is returned in the Get a Profile and Token endpoint your application usually does not need to call this endpoint. It is available for any authentication flows that require an additional endpoint to retrieve a user’s profile.

 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`

`Returns`

profile

Connection

A connection represents the relationship between WorkOS and any collection of application users. This collection of application users may include personal or enterprise identity providers. 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.

Example Connection

 {
  "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`

Get a Connection

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

`/connections/:id`

`Parameters`

`Returns`

connection

List Connections

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`

`Returns` `object`

Delete a Connection

Delete an existing connection.

Request

 curl --request DELETE \
  --url https://api.workos.com/connections/conn_01E2NPPCT7XQ2MVVYDHWGK1WN4 \
  --header "Authorization: Bearer sk_example_123456789"

DELETE

`/connections/:id`

`Parameters`

Directory Sync

Directory Sync allows you to connect with directory providers to inform your application of any changes in their users, groups, or access rules.

Using Directory Sync, one integration grants your application the ability to support multiple directory providers. Get real-time updates of any changes to the organization’s access rules, groups, and users by integrating webhooks into your application.

To automatically respond to changes in the connected directories and their users and groups, use the Directory Sync events.

Get a Directory

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

`/directory/:id`

`Parameters`

`Returns`

directory

List Directories

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`

`Returns` `object`

Delete a Directory

Delete an existing directory.

Request

 curl --request DELETE \
  --url https://api.workos.com/directories/directory_01ECAZ4NV9QMV47GW873HDCX74 \
  --header "Authorization: Bearer sk_example_123456789"

DELETE

`/directories/:id`

`Parameters`

Directory User

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.

Example Directory User

 {
  "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": {},
  "role": { "slug": "member" }
}

`directory_user`

Get a Directory User

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": {},
  "role": { "slug": "member" }
}

GET

`/directory_users/:id`

`Parameters`

`Returns`

directory_user

List Directory Users

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"
      },
      "role": { "slug": "member" }
    },
    {
      "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"
      },
      "role": { "slug": "member" }
    }
  ],
  "object": "list",
  "list_metadata": {
    "after": "directory_user_01E4RH82CC8QAP8JTRCTNDSS4C",
    "before": "directory_user_01E4RH828021B9ZZB8KH8E2Z1W"
  }
}

GET

`/directory_user`

`Parameters`

`Returns` `object`

Directory Group

A directory group represents an organizational unit of users in a directory provider.

Example Directory Group

 {
  "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`

Get a Directory Group

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`

`Returns`

directory_group

List Directory Groups

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`

`Returns` `object`

Admin Portal

The Admin Portal is a standalone application where your users can configure and manage WorkOS resources such as Connections and Directories that are scoped to their Organization.

Portal Link

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

Example Portal Link URL

 https://setup.workos.com?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Generate a Portal Link

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`

`Returns` `object`

Audit Logs

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.

Create Event

Emits an Audit Log Event.

Request

 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`

Create Schema

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.

Request

cURL

 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`

List Schemas

Get a list of all schemas for the Audit Logs action identified by :name.

cURL

 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`

`Returns` `object`

List Actions

Get a list of all Audit Log actions in the current environment.

cURL

 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`

`Returns` `object`

Audit Log Export

An object representing an Audit Log Export.

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`

Create Export

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`

`Returns`

audit_log_export

Get Export

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"
}

GET

`/audit_logs/exports/:id`

`Parameters`

`Returns`

audit_log_export

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 Retention

Get the configured event retention period for the given Organization.

cURL

 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`

`Returns` `object`

Set Retention

Set the event retention period for the given Organization.

cURL

 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`

`Returns` `object`

Organization domain

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.

Example organization domain

 {
  "object": "organization_domain",
  "id": "org_domain_01HEJXJSTVEDT7T58BM70FMFET",
  "organization_id": "org_01EHT88Z8J8795GZNQ4ZP1J81T",
  "domain": "foo-corp.com",
  "state": "pending",
  "verification_strategy": "dns",
  "verification_token": "aW5HQ8Sgps1y3LQyrShsFRo3F"
}

Get an Organization Domain

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": "foo-corp.com",
  "state": "pending",
  "verification_strategy": "dns",
  "verification_token": "aW5HQ8Sgps1y3LQyrShsFRo3F"
}

GET

`/organization_domains/:id`

`Parameters`

`Returns`

organization_domain

Create an Organization Domain

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": "foo-corp.com",
  "state": "pending",
  "verification_strategy": "dns",
  "verification_token": "aW5HQ8Sgps1y3LQyrShsFRo3F"
}

POST

`/organization-domains`

`Parameters`

`Returns`

organization_domain

Verify an Organization Domain

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": "foo-corp.com",
  "state": "pending",
  "verification_strategy": "dns",
  "verification_token": "oNKzjqppp347rDBgLA5dTo8uA"
}

POST

`/organization-domains/:id/verify`

`Parameters`

`Returns`

organization_domain

Authentication Factor

An object representing an Authentication Factor.

Example 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`

Authentication Challenge

An object representing a Challenge of an Authentication Factor.

Example Authentication 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"
}

`authentication_challenge`

Enroll Factor

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`

`Returns`

authentication_factor

Challenge Factor

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`

`Returns`

authentication_challenge

Verify Challenge

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`

`Returns` `object`

Get Factor

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"
  }
}

GET

`/auth/factors/:id`

`Parameters`

`Returns`

authentication_factor

Delete Factor

Deletes an Authentication Factor.

Request

 curl --request DELETE \
  --url https://api.workos.com/auth/factors/auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ \
  --header "Authorization: Bearer sk_example_123456789"

DELETE

`/auth/factors/:id`

`Parameters`

Magic Link

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.

Passwordless SessionDeprecated

An object representing a passwordless authentication session.

Example Passwordless 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`

Create Passwordless SessionDeprecated

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`

`Returns`

passwordless_session

Email a Magic LinkDeprecated

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
}

POSTSends email

API reference

Client libraries

Testing the API

API Keys

Secure your API Keys

In Staging

In Production

Errors

Pagination

Parameters

before?: string

after?: string

limit?: number

order?: "asc" | "desc"

Idempotency

Rate limits

General

Single Sign-On

Directory Sync

User Management

Hosted AuthKit

Events

List events

/events

Parameters

events: array

organization_id: string

limit?: number

range_start?: string

range_end?: string

after?: string

Returns object

data: array

list_metadata: object

Organization

organization

object: "organization"

id: string

name: string

created_at: string

updated_at: string

domains: array

Get an Organization

/organizations/:id

Parameters

id: string

Returns

List Organizations

/organizations

Parameters

domains?: string[]

limit?: number

before?: string

after?: string

order?: "asc" | "desc"

Returns object

data: array

list_metadata: object

Create an Organization

/organizations

Parameters

name: string

domain_data?: array

Returns

Update an Organization

/organizations/:id

Parameters

name: string

domain_data?: array

Returns

Delete an Organization

/organizations/:id

Parameters

id: string

Organization Domain

organization_domain

object: "organization_domain"

id: string

domain: string

User Management

`Parameters`

`/events`

`Parameters`

`Returns` `object`

`organization`

`/organizations/:id`

`Parameters`

`Returns`

`/organizations`

`Parameters`

`Returns` `object`

`/organizations`

`Parameters`

`Returns`

`/organizations/:id`

`Parameters`

`Returns`

`/organizations/:id`

`Parameters`

`organization_domain`

`user`

`/user_management/users/:id`

`Parameters`

`Returns`

`/user_management/users`

`Parameters`

`Returns` `object`

`/user_management/users`

`Parameters`

`Returns`

`/user_management/users/:id`

`Parameters`

`Returns`

`/user_management/users/:id`

`Parameters`

`/user_management/authorize`

`Returns`