Authentication API Domain

WorkOS authentication requests are done via the Authentication API, which defaults to api.workos.com. This can be configured to a custom domain if you prefer to use your own branding instead of the default.

While developing with WorkOS in a Sandbox environment, requests are made to the api.workos.com domain. In production environments, requests are made to api.workos.com by default or a custom domain if configured.

For instance, if you were retrieving a user via the API and you had a custom Authentication API domain api.example.com set up, you’d make requests to:

https://api.example.com/user_management/users/:id

Instead of the default:

https://api.workos.com/user_management/users/:id

Custom Authentication API domains are also used for SCIM endpoints when using Directory Sync. For example, if you had a custom domain api.example.com set up, your customer’s identity provider would make requests to https://api.example.com/scim/v2.0/:id. The custom domain is reflected in the Admin Portal setup steps for a directory.

Adding a custom domain does not affect existing directory integrations pointing to api.workos.com.

When using the WorkOS SDKs, a custom API hostname can be configured:

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

const workos = new WorkOS('sk_example_123456789', {
  clientId: 'client_123456789',
  apiHostname: 'api.workos.com',
});

With the production environment selected, navigate to the Domains section of the WorkOS Dashboard.

Click the Configure authentication API domain button and enter the domain you would like to use.

You will be prompted to add a CNAME record to your DNS provider. If your DNS provider is Cloudflare, ensure the CNAME record is configured as DNS-only and is not proxied. To manage custom domains, WorkOS uses Cloudflare, who prohibit domains from being proxied across accounts.

Once your domain is successfully verified, your custom domain will act as the ACS URL for authentication.