Organization domains

An organization domain is a domain your customer owns — such as acmecorp.com. Proving domain ownership unlocks two key features:

• Home Realm Discovery (SSO): When a user signs in with an email address matching a registered domain, Scalekit automatically routes them to that organization’s SSO identity provider.
• SCIM Provisioning: Scalekit only processes SCIM user lifecycle events (create, update, deactivate) for users whose email domain matches a registered organization domain. This ensures only the organization that owns a domain can manage those users.

Add and verify an organization domain

Via Admin Portal No-code

The Admin Portal gives the admin of a customer organization a self-serve way to add and verify their domain — without involving your engineering team. This is the recommended approach for production onboarding.

1. Enable domain verification for the organization

   Turn on the Domain Verification feature for the organization. You can do this in the Scalekit Dashboard (navigate to Organizations → select the organization → Overview → toggle Domain Verification), or via the API:

   cURL

   Enable domain_verification feature

   curl --request PATCH \
     'https://<SCALEKIT_ENVIRONMENT_URL>/api/v1/organizations/<organization_id>/settings' \
     --header 'Authorization: Bearer <ACCESS_TOKEN>' \
     --header 'Content-Type: application/json' \
     --data '{
       "features": [{ "name": "domain_verification", "enabled": true }]
     }'

   Node.js

   Enable domain_verification feature

   await scalekit.organization.updateOrganizationSettings(organizationId, {
     features: [{ name: 'domain_verification', enabled: true }],
   });

   Python

   Enable domain_verification feature

   scalekit_client.organization.update_organization_settings(
       organization_id,
       [{"name": "domain_verification", "enabled": True}],
   )

   Go

   Enable domain_verification feature

   err = scalekitClient.Organization.UpdateOrganizationSettings(
       ctx,
       organizationID,
       scalekit.OrganizationSettings{
           Features: []scalekit.OrganizationSettingsFeature{
               {Name: "domain_verification", Enabled: true},
           },
       },
   )

   Java

   Enable domain_verification feature

   scalekitClient.organizations().updateOrganizationSettings(
       organizationId,
       List.of(new Feature().setName("domain_verification").setEnabled(true))
   );

2. Generate an Admin Portal link and embed in your app

   Generate an admin portal link and embed in your application:

   cURL

   Generate portal link for domain verification

   curl 'https://<SCALEKIT_ENVIRONMENT_URL>/api/v1/organizations/<organization_id>/portal_links' \
     --header 'Authorization: Bearer <ACCESS_TOKEN>'

   Node.js

   Generate portal link for domain verification

   const link = await scalekit.organization.generatePortalLink(organizationId);
   // Redirect the org admin to link.location

   Python

   Generate portal link for domain verification

   link = scalekit_client.organization.generate_portal_link(organization_id)
   # Redirect the org admin to link.location

   Go

   Generate portal link for domain verification

   link, err := scalekitClient.Organization().GeneratePortalLink(ctx, organizationID)
   // Redirect the org admin to link.Link.Location

   Java

   Generate portal link for domain verification

   Link link = scalekitClient.organizations().generatePortalLink(
       organizationId,
       Arrays.asList(Feature.domain_verification)
   );
   // Redirect the org admin to link.getLocation()

3. Organization admin adds the domain and publishes the DNS record

   The admin opens the portal link, clicks Add domain, and enters their domain name. The portal displays the TXT record to add and verify domain ownership. The admin adds this record in their DNS provider (e.g., Cloudflare, Route 53, GoDaddy). Propagation typically takes a few minutes but can take up to 48 hours.

   

4. Scalekit verifies the DNS record

   Scalekit polls the domain’s DNS automatically. Once the TXT record is detected, the domain status changes to Verified and SSO routing and SCIM become active.

Via Hosted Widgets No-code

Firstly, turn on the Domain Verification feature for the organization. Then, redirect the end users to Hosted widgets to manage their organization’s domains. The domain verification flow inside the widget is identical to the Admin Portal: the user enters a domain, the widget displays the TXT record to publish, and Scalekit verifies in the background.

Via Scalekit Dashboard No-code

Your team can add organization domains directly from the Scalekit Dashboard, useful for initial setup or when you have already verified ownership through other means.

1. Go to Dashboard > Organizations and select the target organization.
2. Navigate to Overview > Organization Domains.
3. Click Add domain and enter the domain name.

Domains added this way are marked as Admin-verified, no DNS verification is required. They become active for SSO routing and SCIM immediately.

Via API API

Add and manage organization domains programmatically. Domains created via the API are also Admin-verified by default, no DNS verification is required. Use this when you have already confirmed domain ownership through another process and want to activate SSO routing or SCIM immediately.

cURL

Manage organization domains

# 1. Add an organization domain
curl 'https://<SCALEKIT_ENVIRONMENT_URL>/api/v1/organizations/<organization_id>/domains' \
  --request POST \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "domain": "acmecorp.com",
    "domain_type": "ORGANIZATION_DOMAIN"
  }'

# 2. List all organization domains
curl 'https://<SCALEKIT_ENVIRONMENT_URL>/api/v1/organizations/<organization_id>/domains?domain_type=ORGANIZATION_DOMAIN' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>'

# 3. Get details of a specific domain
curl 'https://<SCALEKIT_ENVIRONMENT_URL>/api/v1/organizations/<organization_id>/domains/<domain_id>' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>'

# 4. Delete a domain
curl 'https://<SCALEKIT_ENVIRONMENT_URL>/api/v1/organizations/<organization_id>/domains/<domain_id>' \
  --request DELETE \
  --header 'Authorization: Bearer <ACCESS_TOKEN>'

Node.js

Manage organization domains

import { Scalekit } from '@scalekit-sdk/node';

const scalekit = new Scalekit(
  process.env.SCALEKIT_ENVIRONMENT_URL,
  process.env.SCALEKIT_CLIENT_ID,
  process.env.SCALEKIT_CLIENT_SECRET,
);

// 1. Add an organization domain
const newDomain = await scalekit.organization.createDomain(organizationId, {
  domain: 'acmecorp.com',
  domainType: 'ORGANIZATION_DOMAIN',
});
// newDomain.txtRecordKey and newDomain.txtRecordSecret contain the DNS record values

// 2. List all organization domains
const { domains } = await scalekit.organization.listDomains(organizationId, {
  domainType: 'ORGANIZATION_DOMAIN',
});

// 3. Get a specific domain
const domain = await scalekit.organization.getDomain(organizationId, domainId);

// 4. Delete a domain
await scalekit.organization.deleteDomain(organizationId, domainId);

Python

Manage organization domains

from scalekit import Scalekit
import os

scalekit_client = Scalekit(
    environment_url=os.environ.get("SCALEKIT_ENVIRONMENT_URL"),
    client_id=os.environ.get("SCALEKIT_CLIENT_ID"),
    client_secret=os.environ.get("SCALEKIT_CLIENT_SECRET"),
)

# 1. Add an organization domain
new_domain = scalekit_client.organization.create_domain(
    organization_id,
    domain="acmecorp.com",
    domain_type="ORGANIZATION_DOMAIN",
)
# new_domain.txt_record_key and new_domain.txt_record_secret contain the DNS record values

# 2. List all organization domains
domains = scalekit_client.organization.list_domains(
    organization_id, domain_type="ORGANIZATION_DOMAIN"
)

# 3. Get a specific domain
domain = scalekit_client.organization.get_domain(organization_id, domain_id)

# 4. Delete a domain
scalekit_client.organization.delete_domain(organization_id, domain_id)

Go

Manage organization domains

import (
    "context"
    "os"

    "github.com/scalekit/sdk-go"
)

scalekitClient := scalekit.New(
    os.Getenv("SCALEKIT_ENVIRONMENT_URL"),
    os.Getenv("SCALEKIT_CLIENT_ID"),
    os.Getenv("SCALEKIT_CLIENT_SECRET"),
)

ctx := context.Background()

// 1. Add an organization domain
newDomain, err := scalekitClient.Organization().CreateDomain(ctx, organizationID, scalekit.CreateDomainOptions{
    Domain:     "acmecorp.com",
    DomainType: "ORGANIZATION_DOMAIN",
})
// newDomain.TxtRecordKey and newDomain.TxtRecordSecret contain the DNS record values

// 2. List all organization domains
domains, err := scalekitClient.Organization().ListDomains(ctx, organizationID, scalekit.ListDomainsOptions{
    DomainType: "ORGANIZATION_DOMAIN",
})

// 3. Get a specific domain
domain, err := scalekitClient.Organization().GetDomain(ctx, organizationID, domainID)

// 4. Delete a domain
err = scalekitClient.Organization().DeleteDomain(ctx, organizationID, domainID)

Java

Manage organization domains

import com.scalekit.client.Scalekit;

Scalekit scalekitClient = new Scalekit(
    System.getenv("SCALEKIT_ENVIRONMENT_URL"),
    System.getenv("SCALEKIT_CLIENT_ID"),
    System.getenv("SCALEKIT_CLIENT_SECRET")
);

// 1. Add an organization domain
Domain newDomain = scalekitClient.organizations()
    .createDomain(organizationId, new CreateDomainOptions()
        .setDomain("acmecorp.com")
        .setDomainType("ORGANIZATION_DOMAIN"));
// newDomain.getTxtRecordKey() and newDomain.getTxtRecordSecret() contain the DNS record values

// 2. List all organization domains
List<Domain> domains = scalekitClient.organizations()
    .listDomains(organizationId, new ListDomainsOptions()
        .setDomainType("ORGANIZATION_DOMAIN"));

// 3. Get a specific domain
Domain domain = scalekitClient.organizations().getDomain(organizationId, domainId);

// 4. Delete a domain
scalekitClient.organizations().deleteDomain(organizationId, domainId);

Listen for organization domain events

Subscribe to these webhook events to react to domain lifecycle changes in your application:

Event	Fires when
organization.domain_created	A domain is added to an organization via any method
organization.domain_deleted	A domain is removed from an organization
organization.domain_dns_verification_success	The DNS check confirms domain ownership
organization.domain_dns_verification_failed	The DNS verification window expired without a successful DNS match

See Organization domain events for the full event payload schema.

Common scenarios

How is organization domains different from allowed email domains?

Allowed email domains let users with a matching email address see and join the organization via the organization switcher.

Organization domains prove domain ownership by an organization and unlock SSO routing (Home Realm Discovery) and SCIM provisioning. The distinction is about what the domain enables, not just who can join.

What happens if DNS hasn’t propagated yet?

DNS propagation can take anywhere from a few minutes to 48 hours depending on the TTL and the DNS provider.

Scalekit polls the domain on a scheduled interval and retries automatically until the TXT record is found or the verification window expires. The org admin can also click Verify now in the Admin Portal or Hosted Widget to trigger an immediate check at any time.

If the window expires before the record propagates, the domain status moves to FAILED. Delete the domain and add it again to get a fresh verification token and restart the process.

Can I verify a domain without DNS?

Yes. Domains added via the Scalekit Dashboard or API are marked as Admin-verified, no DNS verification is required. Use this when you have already confirmed domain ownership through another process (contract, business verification, etc.) and want to activate SSO routing or SCIM immediately.