API

Programmatic domain verification

Instead of leveraging the Admin Portal, the Domain Verification API can be used to verify domains programmatically.

Integrating with the API goes as follows:

Create an organization domain for an organization
Share the token and setup instructions with the organization owner (IT admin)
Wait for the verification to complete

Create a new organization domain

All domains belong to an organization. In order to create and verify a domain, an organization must first be created.

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

const workos = new WorkOS('sk_example_123456789');

// Creates a new organization.
// You can also fetch an existing organization with workos.organizations.getOrganization(id)
const organization = await workos.organizations.createOrganization({
  name: 'Foo Corp',
});

// Creates the organization domain
const organizationDomain = await workos.organizationDomains.create({
  organizationId: organization.id,
  domain: 'workos.com',
});

The verification_token returned can then be set as the value of a TXT record that WorkOS will periodically check until the record is found. The TXT record for the above response example would be:

Name: domain-to-verify.com
Value: verification_token=3CVZxo4HgvSiYRKlV4RdOWwWl

Get a domain

Fetch an existing domain and it’s current verification status. This endpoint can be polled once verification has been initiated to determine if verification has been successful.

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

const workos = new WorkOS('sk_example_123456789');

const organizationDomainId = 'org_domain_0123ABCD';

// Fetch the organization domain by Id
const organizationDomain =
  await workos.organizationDomains.get(organizationDomainId);

// Check organization state
switch (organizationDomain) {
  case OrganizationDomainState.Verified:
  case OrganizationDomainState.Pending:
  case OrganizationDomainState.Failed:
    return;
}

Possible state values:

pending: domain verification has been initiated and not yet completed
verified: domain has been verified
failed: domain was not able to be verified

Possible verification_strategy values:

dns: domain is verified with the DNS flow
developer: domain is verified by a person or a system, without running the DNS flow

Initiate verification for existing domain

If a domain has not successfully verified within thirty days and moves to the failed state, verification can be restarted manually.

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

const workos = new WorkOS('sk_example_123456789');

const organizationDomainId = 'org_domain_01EZTR5N6Y9RQKHK2E9F31KZX6';

// Initiate verification by Organization Domain ID
const organizationDomainVerifying =
  await workos.organizationDomains.verify(organizationDomainId);