---
title: "Verify an org domain"
method: POST
path: "/org-domain/{id}/verify"
tags: ["Org domains"]
---

# Verify an org domain

`POST /org-domain/{id}/verify`

## Request

- Base URL: `https://api.elaichi.ai`
- URL: `https://api.elaichi.ai/org-domain/{id}/verify`
- Auth: HTTP bearer

Verifies a claimed org domain. Runs the DNS TXT challenge now. Idempotent and safe to poll. Returns the domain plus `detail`, which explains a failed lookup (`detail` appears only on this response). Requires `org:manage`. A browser session must also pass a fresh step-up reauthentication in the app (without it the call answers `428 step_up_required`). An organization API token is not challenged.

## Path parameters

- `id` string, required

## Headers

- `X-Organization-Id` string

## Response `200`

OK

- object
  - `id` string: Org domain id.
  - `organization_id` string: Owning organization (`org_…`).
  - `domain` string: DNS name, lowercased (e.g. `acme.com`).
  - `verified` boolean: Outcome of this attempt.
  - `verification_record` string, nullable: The exact DNS TXT value to publish. Present until the domain is verified, then null — the token is of no further use.
  - `default_role_id` string, nullable: Role (`role_…`) explicitly configured for domain auto-join, or null to track the default. Org Owner is refused here. Read `effective_default_role_id` to learn what a join actually grants.
  - `effective_default_role_id` string, nullable: Server-computed: the role a verified-domain auto-join really grants. Equals `default_role_id` when that is set and the role still exists; otherwise the **Member** system role, which is what the join falls back to both when nothing is configured and when the configured role has since been deleted. `null` means even that fallback is missing, so auto-join on this domain fails rather than seating anyone.
  - `sso_connection_id` string, nullable: Linked SSO connection (`sso_…`).
  - `created_at` string, date-time
  - `updated_at` string, date-time
  - `detail` string, nullable: Why verification failed, when it did.

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not found
- `429`: Rate limited

---

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