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 contact)
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.

JavaScript

 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',
});

 {
  "id": "org_domain_01HACSKJ57W8M2Q0N2X759C5HS",
  "organization_id": "org_123",
  "domain": "domain-to-verify.com",
  "state": "pending",
  "verification_token": "3CVZxo4HgvSiYRKlV4RdOWwWl",
  "verification_strategy": "dns"
}

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.

JavaScript

 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;
}

 {
  "id": "org_domain_01HACSKJ57W8M2Q0N2X759C5HS",
  "organization_id": "org_123",
  "domain": "domain-to-verify.com",
  "state": "verified",
  "verification_token": "3CVZxo4HgvSiYRKlV4RdOWwWl",
  "verification_strategy": "dns"
}

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
manual: 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.

JavaScript

 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);

 {
  "id": "org_domain_01HACSKJ57W8M2Q0N2X759C5HS",
  "organization_id": "org_123",
  "domain": "domain-to-verify.com",
  "state": "pending",
  "verification_token": "3CVZxo4HgvSiYRKlV4RdOWwWl",
  "verification_strategy": "dns"
}