The Organizations API allows you to create, retrieve, update, and delete organizations, as well as manage organization-specific resources like roles, feature flags, and API keys.
Initialize import { WorkOS } from '@workos-inc/node' ; const workos = new WorkOS ( 'sk_example_123456789' );
Methods listOrganizations Retrieve a list of organizations.
const organizations = await workos . organizations . listOrganizations ({ domains: [ 'example.com' ], limit: 10 , }); for await ( const organization of organizations ) { console . log ( organization . id , organization . name ); }
Options for filtering and paginating organizations. Filter organizations by domains.
Cursor for pagination, fetching records before this ID.
Cursor for pagination, fetching records after this ID.
Maximum number of records to return (default: 10).
organizations
AutoPaginatable<Organization>
An auto-paginatable list of organizations. Show Organization properties
Unique identifier for the organization.
Name of the organization.
allowProfilesOutsideOrganization
Whether profiles outside the organization are allowed.
List of verified and pending domains.
Stripe customer ID if configured.
External identifier for the organization.
Custom metadata key-value pairs.
ISO-8601 timestamp of creation.
ISO-8601 timestamp of last update.
createOrganization Create a new organization.
const organization = await workos . organizations . createOrganization ({ name: 'Acme Corporation' , domainData: [ { domain: 'acme.com' , state: 'verified' }, ], externalId: 'external_123' , metadata: { industry: 'technology' }, });
payload
CreateOrganizationOptions
required
The organization data. Name of the organization.
Array of domain objects to associate with the organization.
External identifier for syncing with your system.
Custom metadata as key-value pairs.
requestOptions
CreateOrganizationRequestOptions
Unique key to ensure idempotent requests.
The created organization object.
getOrganization Retrieve an organization by ID.
const organization = await workos . organizations . getOrganization ( 'org_123' );
The unique identifier of the organization.
getOrganizationByExternalId Retrieve an organization by external ID.
const organization = await workos . organizations . getOrganizationByExternalId ( 'external_123' );
The external identifier of the organization.
updateOrganization Update an existing organization.
const organization = await workos . organizations . updateOrganization ({ organization: 'org_123' , name: 'Acme Corp (Updated)' , metadata: { industry: 'fintech' }, });
options
UpdateOrganizationOptions
required
The ID of the organization to update.
Updated name of the organization.
The updated organization object.
deleteOrganization Delete an organization.
await workos . organizations . deleteOrganization ( 'org_123' );
The unique identifier of the organization to delete.
listOrganizationRoles Retrieve all roles for an organization.
const roleList = await workos . organizations . listOrganizationRoles ({ organizationId: 'org_123' , }); console . log ( roleList . data );
options
ListOrganizationRolesOptions
required
The ID of the organization.
listOrganizationFeatureFlags Retrieve feature flags for an organization.
const featureFlags = await workos . organizations . listOrganizationFeatureFlags ({ organizationId: 'org_123' , limit: 20 , }); for await ( const flag of featureFlags ) { console . log ( flag . key , flag . enabled ); }
options
ListOrganizationFeatureFlagsOptions
required
The ID of the organization.
Maximum number of records to return.
featureFlags
AutoPaginatable<FeatureFlag>
An auto-paginatable list of feature flags.
listOrganizationApiKeys Retrieve API keys for an organization.
const apiKeys = await workos . organizations . listOrganizationApiKeys ({ organizationId: 'org_123' , limit: 10 , }); for await ( const apiKey of apiKeys ) { console . log ( apiKey . id , apiKey . name ); }
options
ListOrganizationApiKeysOptions
required
The ID of the organization.
Maximum number of records to return.
An auto-paginatable list of API keys.
createOrganizationApiKey Create an API key for an organization.
const apiKey = await workos . organizations . createOrganizationApiKey ({ organizationId: 'org_123' , name: 'Production API Key' , }); console . log ( apiKey . secret ); // Only returned on creation
options
CreateOrganizationApiKeyOptions
required
The ID of the organization.
requestOptions
CreateOrganizationApiKeyRequestOptions
Unique key to ensure idempotent requests.
The created API key object including the secret (only returned once).