An organization domain represents an 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 or update APIs. Domains can also be verified through a self-serve flow 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.
Get the details of an existing organization domain.
curl "https://api.workos.com/organization_domains/org_domain_01EHZNVPK2QXHMVWCEDQEKY69A" \ --header "Authorization: Bearer sk_example_123456789"
{ "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" }
| curl "https://api.workos.com/organization_domains/org_domain_01EHZNVPK2QXHMVWCEDQEKY69A" \ | |
| --header "Authorization: Bearer sk_example_123456789" |
| import { WorkOS } from '@workos-inc/node'; | |
| const workos = new WorkOS('sk_example_123456789'); | |
| const organization = await workos.organizationDomains.get( | |
| 'org_domain_01HEJXJSTVEDT7T58BM70FMFET', | |
| ); |
| require "workos" | |
| WorkOS.configure do |config| | |
| config.api_key = "sk_example_123456789" | |
| end | |
| WorkOS.client.organization_domains.get_organization_domain(id: "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A") |
| 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" | |
| ) |
| package main | |
| import ( | |
| "context" | |
| "github.com/workos/workos-go/v9" | |
| ) | |
| func main() { | |
| client := workos.NewClient("sk_example_123456789") | |
| _, err := client.OrganizationDomains().Get(context.Background(), "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A") | |
| if err != nil { | |
| panic(err) | |
| } | |
| } |
| <?php | |
| use WorkOS\WorkOS; | |
| $workos = new WorkOS( | |
| apiKey: "sk_example_123456789", | |
| clientId: "client_123456789", | |
| ); | |
| $workos | |
| ->organizationDomains() | |
| ->getOrganizationDomain(id: "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A"); |
| import com.workos.WorkOS; | |
| WorkOS workos = new WorkOS("sk_example_123456789"); | |
| workos.organizationDomains.getOrganizationDomain("org_domain_01EHZNVPK2QXHMVWCEDQEKY69A"); |
| using WorkOS; | |
| var client = new WorkOSClient(new WorkOSOptions { | |
| ApiKey = "sk_example_123456789", | |
| ClientId = "client_123456789", | |
| }); | |
| await client.OrganizationDomains.GetAsync("org_domain_01EHZNVPK2QXHMVWCEDQEKY69A"); |
| 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(()) | |
| } |
| { | |
| "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" | |
| } |
GET/organization_domains /:idParameters Returns Creates a new Organization Domain.
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
{ "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" }
| 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 |
| 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', | |
| }); |
| 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" | |
| ) |
| 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" | |
| ) |
| package main | |
| import ( | |
| "context" | |
| "github.com/workos/workos-go/v9" | |
| ) | |
| 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 | |
| use WorkOS\WorkOS; | |
| $workos = new WorkOS( | |
| apiKey: "sk_example_123456789", | |
| clientId: "client_123456789", | |
| ); | |
| $workos | |
| ->organizationDomains() | |
| ->createOrganizationDomain( | |
| domain: "foo-corp.com", | |
| organizationId: "org_01EHQMYV6MBK39QC5PZXHY59C3", | |
| ); |
| 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); |
| 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", | |
| }); |
| 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(()) | |
| } |
| { | |
| "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" | |
| } |
POST/organization_domainsReturns Initiates verification process for an Organization Domain.
curl --request POST \ --url "https://api.workos.com/organization_domains/org_domain_01EHZNVPK2QXHMVWCEDQEKY69A/verify" \ --header "Authorization: Bearer sk_example_123456789"
{ "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" }
| curl --request POST \ | |
| --url "https://api.workos.com/organization_domains/org_domain_01EHZNVPK2QXHMVWCEDQEKY69A/verify" \ | |
| --header "Authorization: Bearer sk_example_123456789" |
| import { WorkOS } from '@workos-inc/node'; | |
| const workos = new WorkOS('sk_example_123456789'); | |
| const organization = await workos.organizationDomains.verify( | |
| 'org_domain_01HEJXJSTVEDT7T58BM70FMFET', | |
| ); |
| require "workos" | |
| WorkOS.configure do |config| | |
| config.api_key = "sk_example_123456789" | |
| end | |
| WorkOS.client.organization_domains.verify_organization_domain(id: "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A") |
| 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" | |
| ) |
| package main | |
| import ( | |
| "context" | |
| "github.com/workos/workos-go/v9" | |
| ) | |
| func main() { | |
| client := workos.NewClient("sk_example_123456789") | |
| _, err := client.OrganizationDomains().Verify(context.Background(), "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A") | |
| if err != nil { | |
| panic(err) | |
| } | |
| } |
| <?php | |
| use WorkOS\WorkOS; | |
| $workos = new WorkOS( | |
| apiKey: "sk_example_123456789", | |
| clientId: "client_123456789", | |
| ); | |
| $workos | |
| ->organizationDomains() | |
| ->verifyOrganizationDomain(id: "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A"); |
| import com.workos.WorkOS; | |
| WorkOS workos = new WorkOS("sk_example_123456789"); | |
| workos.organizationDomains.verifyOrganizationDomain( | |
| "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A"); |
| using WorkOS; | |
| var client = new WorkOSClient(new WorkOSOptions { | |
| ApiKey = "sk_example_123456789", | |
| ClientId = "client_123456789", | |
| }); | |
| await client.OrganizationDomains.VerifyAsync("org_domain_01EHZNVPK2QXHMVWCEDQEKY69A"); |
| 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(()) | |
| } |
| { | |
| "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" | |
| } |
POST/organization_domains /:id /verifyParameters Returns Permanently deletes an organization domain. It cannot be undone.
curl --request DELETE \ --url https://api.workos.com/organization_domains/org_domain_01HEJXJSTVEDT7T58BM70FMFET \ --header "Authorization: Bearer sk_example_123456789"
import { WorkOS } from '@workos-inc/node'; const workos = new WorkOS('sk_example_123456789'); await workos.organizationDomains.delete( 'org_domain_01HEJXJSTVEDT7T58BM70FMFET', );
require "workos" WorkOS.configure do |config| config.api_key = "sk_example_123456789" end WorkOS.client.organization_domains.delete_organization_domain(id: "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A")
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" )
package main import ( "context" "github.com/workos/workos-go/v9" ) func main() { client := workos.NewClient("sk_example_123456789") _, err := client.OrganizationDomains().Delete(context.Background(), "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A") if err != nil { panic(err) } }
<?php use WorkOS\WorkOS; $workos = new WorkOS( apiKey: "sk_example_123456789", clientId: "client_123456789", ); $workos ->organizationDomains() ->deleteOrganizationDomain(id: "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A");
import com.workos.WorkOS; WorkOS workos = new WorkOS("sk_example_123456789"); workos.organizationDomains.deleteOrganizationDomain( "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A");
using WorkOS; var client = new WorkOSClient(new WorkOSOptions { ApiKey = "sk_example_123456789", ClientId = "client_123456789", }); await client.OrganizationDomains.DeleteAsync("org_domain_01EHZNVPK2QXHMVWCEDQEKY69A");
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(()) }
DELETE/organization_domains /:idParameters Returns