Constructor Create a new WorkOS client instance.
new WorkOS ( keyOrOptions ?: string | WorkOSOptions , maybeOptions ?: WorkOSOptions )
Parameters Either an API key string or a WorkOSOptions object. When using server-side authentication, you can pass the API key directly as a string. For PKCE/public clients or additional configuration, pass a WorkOSOptions object.
Additional options when the first parameter is an API key string.
WorkOSOptions Your WorkOS API key (starts with sk_). Required for server-side operations. If not provided, the SDK will attempt to read from the WORKOS_API_KEY environment variable.
Your WorkOS Client ID. Required for PKCE/public clients and certain authentication flows. If not provided, the SDK will attempt to read from the WORKOS_CLIENT_ID environment variable.
apiHostname
string
default: "api.workos.com"
The API hostname to use. Override this for testing or custom environments.
Whether to use HTTPS for API requests.
Optional port number to use for API requests.
Request timeout in milliseconds.
Additional configuration options for the underlying fetch requests.
Information about your application to be included in the User-Agent header. Your application version.
Custom fetch implementation. Useful for testing or custom network configurations.
Examples Server-side with API key (string)
Server-side with API key (object)
PKCE/public client (no API key)
With custom configuration
const workos = new WorkOS ( 'sk_test_1234567890' );
Properties baseURL The base URL used for all API requests. Constructed from the https, apiHostname, and port options.
readonly client : HttpClient
The underlying HTTP client used for making requests to the WorkOS API.
clientId readonly clientId ?: string
The WorkOS Client ID, if provided during initialization or via the WORKOS_CLIENT_ID environment variable.
The WorkOS API key, if provided during initialization or via the WORKOS_API_KEY environment variable.
options readonly options : WorkOSOptions
The options object used to configure this WorkOS instance.
version Returns the current version of the WorkOS SDK.
Module Properties The WorkOS client provides access to various WorkOS modules:
actions readonly actions : Actions
Access to the Actions API for managing user actions and verification flows.
apiKeys readonly apiKeys : ApiKeys
Access to the API Keys module for managing API keys.
auditLogs readonly auditLogs : AuditLogs
Access to the Audit Logs API for creating and exporting audit log events.
authorization readonly authorization : Authorization
Access to the Authorization module for managing authorization resources.
directorySync readonly directorySync : DirectorySync
Access to the Directory Sync API for managing directory connections and syncing user data.
Access to the Events API for retrieving events from WorkOS.
featureFlags readonly featureFlags : FeatureFlags
Access to the Feature Flags module for managing feature flag configurations.
Access to the Fine-Grained Authorization (FGA) module.
Access to the MFA API for multi-factor authentication flows.
organizations readonly organizations : Organizations
Access to the Organizations API for managing organizations.
organizationDomains readonly organizationDomains : OrganizationDomains
Access to the Organization Domains module for managing organization domain configurations.
passwordless readonly passwordless : Passwordless
Access to the Passwordless API for passwordless authentication flows.
Access to the Pipes module for managing data pipeline configurations.
Access to PKCE (Proof Key for Code Exchange) utilities for OAuth flows.
Access to the Portal API for generating Admin Portal sessions.
Access to the SSO API for Single Sign-On authentication flows.
userManagement readonly userManagement : UserManagement
Access to the User Management API for managing users, authentication, and sessions.
Access to the Vault module for managing encrypted secrets.
webhooks readonly webhooks : Webhooks
Access to the Webhooks utilities for verifying webhook signatures.
readonly widgets : Widgets
Access to the Widgets module for generating widget tokens and URLs.
Methods requireApiKey() Require an API key for methods that need it.
requireApiKey ( methodName : string ): void
Parameters Name of the method requiring the API key (used in error messages).
Throws ApiKeyRequiredException if no API key was provided during initialization.
Make a GET request to the WorkOS API.
async get < Result = any > ( path : string , options ?: GetOptions ): Promise < { data : Result } >
Parameters Request options. Query parameters to include in the request.
Access token for user-scoped requests.
Warrant token for authorization checks.
Skip the API key requirement check.
Returns The response data from the API.
Make a POST request to the WorkOS API.
async post < Result = any , Entity = any > ( path : string , entity : Entity , options ?: PostOptions ): Promise < { data : Result } >
Parameters The request body to send.
Request options. Query parameters to include in the request.
Idempotency key to prevent duplicate requests.
Warrant token for authorization checks.
Skip the API key requirement check.
Returns The response data from the API.
Make a PUT request to the WorkOS API.
async put < Result = any , Entity = any > ( path : string , entity : Entity , options ?: PutOptions ): Promise < { data : Result } >
Parameters The request body to send.
Request options. Query parameters to include in the request.
Idempotency key to prevent duplicate requests.
Skip the API key requirement check.
Returns The response data from the API.
patch() Make a PATCH request to the WorkOS API.
async patch < Result = any , Entity = any > ( path : string , entity : Entity , options ?: PatchOptions ): Promise < { data : Result } >
Parameters The request body to send.
Request options. Query parameters to include in the request.
Idempotency key to prevent duplicate requests.
Skip the API key requirement check.
Returns The response data from the API.
delete() Make a DELETE request to the WorkOS API.
async delete ( path : string , query ?: any ) : Promise < void >
Parameters Query parameters to include in the request.
deleteWithBody() Make a DELETE request with a request body to the WorkOS API.
async deleteWithBody < Entity = any > ( path : string , entity : Entity ): Promise < void >
Parameters The request body to send.
emitWarning() Emit a warning message to the console.
emitWarning ( warning : string ): void
Parameters The warning message to emit.