API reference

The WorkOS API enables adding Enterprise Ready features to your application. This REST API provides programmatic access to AuthKit (user management), Single Sign-On, Directory Sync, and Audit Log resources.

Sign in to see code examples customized with your API keys and data.

https://api.workos.com

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

npm install @workos-inc/node

You can test the API directly with cURL, or use the Postman collection for convenience.

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.

import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

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

API keys can perform any API request to WorkOS. They should be kept secure and private! Be sure to prevent API keys from being made publicly accessible, such as in client-side code, GitHub, unsecured S3 buckets, and so forth. API keys are prefixed with sk_.

Your Staging Environment comes with an API key already generated for you. Staging API keys may be viewed as often as they are needed and will appear inline throughout our documentation in code examples if you are logged in to your WorkOS account. API requests will be scoped to the provided key’s Environment.

Once you unlock Production access you will need to generate an API Key for it. Production API keys may only be viewed once and will need to be saved in a secure location upon creation of them.

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

200

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.

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.

import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

let list = await workos.sso.listConnections({ limit: 100, order: 'desc' });
let connections = list.data;
let after = list.listMetadata.after;

while (after) {
  list = await workos.sso.listConnections({
    limit: 100,
    after: after,
    order: 'desc',
  });
  connections = connections.concat(list.data);
  after = list.listMetadata.after;
}

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.

This rate limits applies to all environments, staging and production. Exceptions to the general rate limit are listed below.

Rate limiting for AuthKit APIs are enforced on a per environment basis.