---
title: "Claim an email domain for SSO"
method: POST
path: "/organizations/{organizationID}/sso/domains"
tags: ["Organizations"]
---

# Claim an email domain for SSO

`POST /organizations/{organizationID}/sso/domains`

## Request

- Base URL: `https://api.xata.tech`
- URL: `https://api.xata.tech/organizations/{organizationID}/sso/domains`
- Auth: OAuth 2
  - Implicit: `https://auth.xata.io/realms/xata/protocol/openid-connect/auth`
  - Scopes: `org:write`

Claims an email domain and returns the DNS record that proves control of it. A claim is only a note to
ourselves: nothing is registered against the domain until verification succeeds, so claiming a domain neither
affects anyone's sign-in nor stops another organization claiming it first. A domain another organization has
already registered is refused with 409, before any DNS record is published.

## Request body

- ClaimOrganizationSSODomainRequest: Request payload for claiming an email domain for SSO
  - `domain` string, required: Bare email domain to claim, for example acme.com.

## Response `201`

Domain claimed, pending verification

- OrganizationSSODomain: An email domain claimed by an organization for SSO
  - `domain` string, required: The claimed email domain
  - `provider_alias` string, required: The alias an identity provider on this domain will be given. Derived from the organization and the domain, so it is known before the provider exists, which is what lets a client show the redirect URI to register with the provider up front.
  - `verified` boolean, required: Whether control of the domain has been proven through DNS
  - `verification` OrganizationSSODomainVerification: The DNS TXT record that proves an organization controls a domain
    - `record_name` string, required: Name to create the record at
    - `record_type` string, required: DNS record type
    - `record_value` string, required: Value the record must hold
  - `missing_since` string, date-time, nullable: When the daily recheck first found the record missing from a verified domain.
  - `revokes_at` string, date-time, nullable: When the domain stops being verified if the record is still missing.

## Other responses

- `400`: Error returned when the request is malformed or contains invalid parameters
- `401`: Error returned when authentication or authorization fails
- `403`: Single sign-on is not enabled for the organization, or the caller is not an Admin
- `409`: The domain is already registered to another organization
- `5XX`: Unexpected Error

## Changes

- **2026-09-29** `5d5197f76970`: 2 info
  - added the optional property `missing_since` to the response with the `201` status
  - added the optional property `revokes_at` to the response with the `201` status
- **2026-09-24** `a9044087aadf`: 1 info
  - removed the non-success response with the status `404`
- **2026-09-15** `367583102486`: 1 info
  - added the non-success response with the status `409`
- **2026-09-11** `dea04a8fcb58`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/xata/apis/xata-api/changes/organizations/:organizationID/sso/domains/post.md)

---

[API](https://skmtc.dev/xata/apis/xata-api.md) - [All operations](https://skmtc.dev/xata/apis/xata-api/llms.txt) - [OpenAPI document](https://skmtc.dev/xata/apis/xata-api/revisions/3145f2078d68?raw)