<!-- llms.txt: https://workos.com/llms.txt -->

# API

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

Integrating with the API goes as follows:

1. Create an organization domain for an organization
2. Share the token and setup instructions with the organization owner (IT contact)
3. Wait for the verification to complete

## Create a new organization domain

All domains belong to an [organization](https://workos.com/docs/reference/organization). In order to create and verify a domain, an organization must first be [created](https://workos.com/docs/reference/organization/create).

:::code-group{title="Create an organization domain"}

```bash language="curl" title="Request" tab="1"
curl https://api.workos.com/organization_domains \
  --header "Authorization: Bearer sk_example_123456789" \
  -d organization_id="org_123" \
  -d domain="foo-corp.com"
```

```js language="js" title="Request" tab="1"
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.createOrganizationDomain({
  organizationId: organization.id,
  domain: 'workos.com',
});
```

```go language="go" title="Request" tab="1"
package main

import (
	"context"
	workos "github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	// Creates a new organization.
	organization, err := client.Organizations().Create(
		context.Background(),
		&workos.OrganizationsCreateParams{
			Name: "Foo Corp",
		},
	)
	if err != nil {
		// Handle the error...
	}

	// Creates the organization domain
	client.OrganizationDomains().Create(
		context.Background(),
		&workos.OrganizationDomainsCreateParams{
			OrganizationID: organization.ID,
			Domain:         "workos.com",
		},
	)

}
```

```json language="json" title="Response" tab="2"
{
  "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.

:::code-group{title="Fetch an organization domain"}

```bash language="curl" title="Request" tab="1"
curl https://api.workos.com/organization_domains/org_domain_01EZTR5N6Y9RQKHK2E9F31KZX6 \
  --header "Authorization: Bearer sk_example_123456789"
```

```js language="js" title="Request" tab="1"
import { OrganizationDomainState, 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.getOrganizationDomain(organizationDomainId);

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

```go language="go" title="Request" tab="1"
package main

import (
	"context"
	workos "github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	domain, err := client.OrganizationDomains().Get(
		context.Background(),
		"org_domain_0123ABCD",
	)
	if err != nil {
		// Handle the error...
	}

	_ = domain
}
```

```json language="json" title="Response" tab="2"
{
  "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.

:::code-group{title="Verify an existing organization domain"}

```bash language="curl" title="Request" tab="1"
curl https://api.workos.com/organization_domains/org_domain_01EZTR5N6Y9RQKHK2E9F31KZX6/verify \
  --header "Authorization: Bearer sk_example_123456789"
```

```js language="js" title="Request" tab="1"
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.verifyOrganizationDomain(organizationDomainId);
```

```go language="go" title="Request" tab="1"
package main

import (
	"context"
	workos "github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	domain, err := client.OrganizationDomains().Verify(
		context.Background(),
		"org_domain_01EZTR5N6Y9RQKHK2E9F31KZX6",
	)
	if err != nil {
		// Handle the error...
	}

	_ = domain
}
```

```json language="json" title="Response" tab="2"
{
  "id": "org_domain_01HACSKJ57W8M2Q0N2X759C5HS",
  "organization_id": "org_123",
  "domain": "domain-to-verify.com",
  "state": "pending",
  "verification_token": "3CVZxo4HgvSiYRKlV4RdOWwWl",
  "verification_strategy": "dns"
}
```

:::