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.

 curl https://api.workos.com/organization_domains \
  --header "Authorization: Bearer sk_example_123456789" \
  -d organization_id="org_123" \
  -d domain="foo-corp.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: _acme-challenge.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.

 curl https://api.workos.com/organization_domains/org_domain_01EZTR5N6Y9RQKHK2E9F31KZX6 \
  --header "Authorization: Bearer sk_example_123456789"

 {
  "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

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.

 curl https://api.workos.com/organization_domains/org_domain_01EZTR5N6Y9RQKHK2E9F31KZX6/verify \
  --header "Authorization: Bearer sk_example_123456789"

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