The Organization Domains API allows you to create, retrieve, verify, and delete domains associated with organizations.
Initialize
import { WorkOS } from '@workos-inc/node';
const workos = new WorkOS('sk_example_123456789');
Methods
get
Retrieve an organization domain by ID.
const domain = await workos.organizationDomains.get('org_domain_123');
console.log(domain.domain, domain.state);
The unique identifier of the organization domain.
The organization domain object.
Unique identifier for the organization domain.
The domain name (e.g., “example.com”).
ID of the organization this domain belongs to.
Verification state: verified, pending, or failed.
Token used for DNS verification (if using DNS strategy).
verificationStrategy
OrganizationDomainVerificationStrategy
Verification strategy: dns or manual.
ISO-8601 timestamp of creation.
ISO-8601 timestamp of last update.
create
Create a new organization domain.
const domain = await workos.organizationDomains.create({
organizationId: 'org_123',
domain: 'acme.com',
});
console.log(domain.verificationToken);
payload
CreateOrganizationDomainOptions
required
The organization domain data.
The ID of the organization.
The domain name to add (e.g., “example.com”).
The created organization domain object.
verify
Verify an organization domain.
const domain = await workos.organizationDomains.verify('org_domain_123');
console.log(domain.state); // 'verified' if successful
The unique identifier of the organization domain to verify.
The verified organization domain object with updated state.
delete
Delete an organization domain.
await workos.organizationDomains.delete('org_domain_123');
The unique identifier of the organization domain to delete.
Domain Verification
DNS Verification
When creating a domain with the DNS verification strategy, you’ll receive a verificationToken. Add this as a TXT record:
TXT _workos.example.com "verification_token_here"
verify method to complete verification.
Manual Verification
For manual verification, WorkOS will verify domain ownership through alternative means. Contact support for manual verification options.
Example: Complete Domain Setup
// 1. Create the domain
const domain = await workos.organizationDomains.create({
organizationId: 'org_123',
domain: 'acme.com',
});
console.log('Add this TXT record:', domain.verificationToken);
// 2. After DNS propagation, verify the domain
const verifiedDomain = await workos.organizationDomains.verify(domain.id);
if (verifiedDomain.state === 'verified') {
console.log('Domain verified successfully!');
} else {
console.log('Verification failed or still pending');
}
Domain States
Domain ownership has been verified.
Domain is awaiting verification.
Domain verification failed.