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

# Organization domain

An organization domain represents an [organization](https://workos.com/docs/reference/organization)'s domain. Domains can be verified to assert that an organization owns the configured domain which is accomplished through DNS TXT record verification.

Organization domains can be verified manually through the Dashboard, or by setting `state: 'verified'` when adding domains via the [Organization create](https://workos.com/docs/reference/organization/create) or [update](https://workos.com/docs/reference/organization/update) APIs. Domains can also be verified through [a self-serve flow](https://workos.com/docs/domain-verification) via the Admin Portal.
The organization that defines this domain policy exerts authentication policy control over that domain across your application.
For this reason, it is important to verify ownership of manually added domains.
Additionally, WorkOS does not allow addition of common consumer domains, like `gmail.com`.

To automatically respond to changes in the organization domains, use [organization domain events](https://workos.com/docs/events/organization-domain).

## Create an Organization Domain

Creates a new Organization Domain.

:::code-group

```bash language="curl" title="Request" tab="1"
curl --request POST \
  --url "https://api.workos.com/organization_domains" \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  -d @- <<'BODY'
    {
        "domain": "foo-corp.com",
        "organization_id": "org_01EHQMYV6MBK39QC5PZXHY59C3"
    }
BODY
```

```js language="js" title="Request" tab="1"
import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const organization = await workos.organizationDomains.create({
  organizationId: 'org_01EHT88Z8J8795GZNQ4ZP1J81T',
  domain: 'foo-corp.com',
});
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.organization_domains.create_organization_domain(
  domain: "foo-corp.com",
  organization_id: "org_01EHQMYV6MBK39QC5PZXHY59C3"
)
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.organization_domains.create_organization_domain(
    domain="foo-corp.com", organization_id="org_01EHQMYV6MBK39QC5PZXHY59C3"
)
```

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

import (
	"context"

	"github.com/workos/workos-go/v10"
)

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

	_, err := client.OrganizationDomains().Create(context.Background(), &workos.OrganizationDomainsCreateParams{
		Domain:         "foo-corp.com",
		OrganizationID: "org_01EHQMYV6MBK39QC5PZXHY59C3",
	})
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos
    ->organizationDomains()
    ->createOrganizationDomain(
        domain: "foo-corp.com",
        organizationId: "org_01EHQMYV6MBK39QC5PZXHY59C3",
    );
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;
import com.workos.organizationdomains.OrganizationDomainsApi.CreateOrganizationDomainOptions;

WorkOS workos = new WorkOS("sk_example_123456789");

CreateOrganizationDomainOptions options =
    CreateOrganizationDomainOptions.builder()
        .domain("foo-corp.com")
        .organizationId("org_01EHQMYV6MBK39QC5PZXHY59C3")
        .build();

workos.organizationDomains.createOrganizationDomain(options);
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.OrganizationDomains.CreateAsync(new OrganizationDomainsCreateOptions {
    Domain = "foo-corp.com",
    OrganizationId = "org_01EHQMYV6MBK39QC5PZXHY59C3",
});
```

```rust language="rust" title="Request" tab="1"
use workos::Client;
use workos::organization_domains::CreateOrganizationDomainParams;

#[tokio::main]
async fn main() -> Result<(), workos::Error> {
    let client = Client::builder()
        .api_key("sk_example_123456789")
        .client_id("client_123456789")
        .build();

    let _result = client
        .organization_domains()
        .create_organization_domain(
            CreateOrganizationDomainParams {
                domain: "foo-corp.com".into(),
                organization_id: "org_01EHQMYV6MBK39QC5PZXHY59C3".into(),
                ..Default::default()
            }
        )
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "object": "organization_domain",
  "id": "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A",
  "organization_id": "org_01EHQMYV6MBK39QC5PZXHY59C3",
  "domain": "foo-corp.com",
  "state": "pending",
  "verification_prefix": "superapp-domain-verification-z3kjny",
  "verification_token": "m5Oztg3jdK4NJLgs8uIlIprMw",
  "verification_strategy": "dns",
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z"
}
```

:::

## Delete an Organization Domain

Permanently deletes an organization domain. It cannot be undone.

:::code-group{title="Request"}

```bash language="curl"
curl --request DELETE \
  --url https://api.workos.com/organization_domains/org_domain_01HEJXJSTVEDT7T58BM70FMFET \
  --header "Authorization: Bearer sk_example_123456789"
```

```js language="js"
import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

await workos.organizationDomains.delete(
  'org_domain_01HEJXJSTVEDT7T58BM70FMFET',
);
```

```rb language="ruby"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.organization_domains.delete_organization_domain(id: "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A")
```

```py language="python"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.organization_domains.delete_organization_domain(
    id_="org_domain_01EHZNVPK2QXHMVWCEDQEKY69A"
)
```

```go language="go"
package main

import (
	"context"

	"github.com/workos/workos-go/v10"
)

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

	_, err := client.OrganizationDomains().Delete(context.Background(), "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A")
	if err != nil {
		panic(err)
	}
}
```

```php language="php"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos
    ->organizationDomains()
    ->deleteOrganizationDomain(id: "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A");
```

```java language="java"
import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

workos.organizationDomains.deleteOrganizationDomain(
    "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A");
```

```cs language="dotnet"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.OrganizationDomains.DeleteAsync("org_domain_01EHZNVPK2QXHMVWCEDQEKY69A");
```

```rust language="rust"
use workos::Client;

#[tokio::main]
async fn main() -> Result<(), workos::Error> {
    let client = Client::builder()
        .api_key("sk_example_123456789")
        .client_id("client_123456789")
        .build();

    let _result = client
        .organization_domains()
        .delete_organization_domain("org_domain_01EHZNVPK2QXHMVWCEDQEKY69A")
        .await?;

    Ok(())
}
```

:::

## Get an Organization Domain

Get the details of an existing organization domain.

:::code-group

```bash language="curl" title="Request" tab="1"
curl "https://api.workos.com/organization_domains/org_domain_01EHZNVPK2QXHMVWCEDQEKY69A" \
  --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 organization = await workos.organizationDomains.get(
  'org_domain_01HEJXJSTVEDT7T58BM70FMFET',
);
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.organization_domains.get_organization_domain(id: "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A")
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.organization_domains.get_organization_domain(
    id_="org_domain_01EHZNVPK2QXHMVWCEDQEKY69A"
)
```

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

import (
	"context"

	"github.com/workos/workos-go/v10"
)

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

	_, err := client.OrganizationDomains().Get(context.Background(), "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A")
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos
    ->organizationDomains()
    ->getOrganizationDomain(id: "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A");
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

workos.organizationDomains.getOrganizationDomain("org_domain_01EHZNVPK2QXHMVWCEDQEKY69A");
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.OrganizationDomains.GetAsync("org_domain_01EHZNVPK2QXHMVWCEDQEKY69A");
```

```rust language="rust" title="Request" tab="1"
use workos::Client;

#[tokio::main]
async fn main() -> Result<(), workos::Error> {
    let client = Client::builder()
        .api_key("sk_example_123456789")
        .client_id("client_123456789")
        .build();

    let _result = client
        .organization_domains()
        .get_organization_domain("org_domain_01EHZNVPK2QXHMVWCEDQEKY69A")
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "object": "organization_domain",
  "id": "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A",
  "organization_id": "org_01HE8GSH8FQPASKSY27THRKRBP",
  "domain": "foo-corp.com",
  "state": "pending",
  "verification_prefix": "superapp-domain-verification-z3kjny",
  "verification_token": "m5Oztg3jdK4NJLgs8uIlIprMw",
  "verification_strategy": "dns",
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z"
}
```

:::

## Verify an Organization Domain

Initiates verification process for an Organization Domain.

:::code-group

```bash language="curl" title="Request" tab="1"
curl --request POST \
  --url "https://api.workos.com/organization_domains/org_domain_01EHZNVPK2QXHMVWCEDQEKY69A/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 organization = await workos.organizationDomains.verify(
  'org_domain_01HEJXJSTVEDT7T58BM70FMFET',
);
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.organization_domains.verify_organization_domain(id: "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A")
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.organization_domains.verify_organization_domain(
    id_="org_domain_01EHZNVPK2QXHMVWCEDQEKY69A"
)
```

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

import (
	"context"

	"github.com/workos/workos-go/v10"
)

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

	_, err := client.OrganizationDomains().Verify(context.Background(), "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A")
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos
    ->organizationDomains()
    ->verifyOrganizationDomain(id: "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A");
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

workos.organizationDomains.verifyOrganizationDomain(
    "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A");
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.OrganizationDomains.VerifyAsync("org_domain_01EHZNVPK2QXHMVWCEDQEKY69A");
```

```rust language="rust" title="Request" tab="1"
use workos::Client;

#[tokio::main]
async fn main() -> Result<(), workos::Error> {
    let client = Client::builder()
        .api_key("sk_example_123456789")
        .client_id("client_123456789")
        .build();

    let _result = client
        .organization_domains()
        .verify_organization_domain("org_domain_01EHZNVPK2QXHMVWCEDQEKY69A")
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "object": "organization_domain",
  "id": "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A",
  "organization_id": "org_01HE8GSH8FQPASKSY27THRKRBP",
  "domain": "foo-corp.com",
  "state": "pending",
  "verification_prefix": "superapp-domain-verification-z3kjny",
  "verification_token": "m5Oztg3jdK4NJLgs8uIlIprMw",
  "verification_strategy": "dns",
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z"
}
```

:::

### organization_domain

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | "organization_domain" | Yes | Distinguishes the organization domain object. |
| `id` | string | Yes | Unique identifier of the organization domain. |
| `organization_id` | string | Yes | ID of the parent Organization. |
| `domain` | string | Yes | Domain for the organization domain. |
| `state` | "pending" \| "verified" \| "failed" | Yes | Verification state of the domain. |
| `verificationStrategy` | "dns" \| "manual" | Yes | Strategy used to verify the domain |
| `verificationToken` | string | Yes | validation token to be used in DNS TXT record. |

### POST /organization_domains

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `domain` | string | Yes | The domain to add to the organization. |
| `organization_id` | string | Yes | The ID of the organization to add the domain to. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `organization_domain` | object | Distinguishes the organization domain object. |

### DELETE /organization_domains/{id}

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Unique identifier of the organization domain. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `empty` | empty | Returns an empty response on success. |

### GET /organization_domains/{id}

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Unique identifier of the organization domain. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `organization_domain` | object | Distinguishes the organization domain object. |

### POST /organization_domains/{id}/verify

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Unique identifier of the organization domain. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `organization_domain` | object | Distinguishes the organization domain object. |