Claim a domain for an organization

POST /v1/organization-domains · permission organization-domains:write

Adds a domain to an organization. domain may be Unicode or an A-label and is stored as a lower-case A-label. With dns_txt (the default) the domain starts pending; publish the returned TXT record and the domain is verified by :verify or by the scheduled check; a domain not verified within 72 hours becomes expired. manual records your own statement of ownership: the domain is verified at once and the statement is written to the management audit log. Each organization can hold at most 100 domains.

Request

Field Type Required Description
Idempotency-Key header no Optional key (16-64 characters) that makes a retried request safe.
organization_id string yes The organization that claims the domain (org_…).
domain string yes Domain name, at most 253 characters. Public suffixes and free email providers cannot be claimed.
verification_method string no dns_txt (default) or manual.

Request body:

{
  "organization_id": "org_01j9xk3m7q8r2s4t6v8w0y2z4a",
  "domain": "acme.com"
}

Response

201 Created with the domain and an ETag header.

{
  "id": "odm_01j9xk3m7q8r2s4t6v8w0y2z4c",
  "organization_id": "org_01j9xk3m7q8r2s4t6v8w0y2z4a",
  "domain": "acme.com",
  "status": "pending",
  "verification_method": "dns_txt",
  "txt_record_name": "_akp-verify.acme.com",
  "txt_record_value": "idp-verify=EXAMPLEtokenEXAMPLEtokenEXAMPLEtokenEXAMPLEtok",
  "verification_started_at": "2026-10-12T09:30:00.123456Z",
  "verified_at": null,
  "last_checked_at": null,
  "unverified_at": null,
  "next_check_at": "2026-10-12T09:31:00.123456Z",
  "last_failure_code": null,
  "capture_mode": "off",
  "sso_routing_enabled": false,
  "created_at": "2026-10-12T09:30:00.123456Z",
  "updated_at": "2026-10-12T09:30:00.123456Z",
  "version": 1
}

Errors

HTTP code When
400 unknown_field The body has a field that is not in the schema or is read-only.
404 not_found No organization with this ID exists in this environment.
409 conflict This organization already has this domain.
409 domain_already_verified Another organization has already verified this domain.
409 domain_limit_reached The organization already has 100 domains.
409 organization_disabled The organization is disabled.
409 organization_pending_deletion The organization is waiting for self-service deletion; cancel the deletion first.
422 domain_not_claimable The domain is a public suffix or a free email provider.
422 validation_failed A field is invalid (organization_id, domain, verification_method).
401 unauthenticated The credential is missing, invalid or revoked.
403 insufficient_permissions The credential lacks the required permission.
429 rate_limited The rate limit was exceeded; retry after the Retry-After period.
503 service_unavailable A dependency is temporarily unavailable; retry after the Retry-After period.

Example

curl -X POST https://api.eu.keenauth.com/v1/organization-domains \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"organization_id":"org_01j9xk3m7q8r2s4t6v8w0y2z4a","domain":"acme.com"}'