---
title: "Update org domain defaults"
method: PATCH
path: "/org-domain/{id}"
tags: ["Org domains"]
---

# Update org domain defaults

`PATCH /org-domain/{id}`

## Request

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

Updates the defaults of a claimed org domain. Merge-patch: omit a field to leave it alone, send `null` to clear it. `default_role_id` is the role granted on domain auto-join — Org Owner is refused, since that would auto-elevate anyone with an address on the domain. `sso_connection_id` must name an SSO connection in this organization. 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

## Request body

- object
  - `default_role_id` string, nullable: Role id (`role_…`), or null to clear.
  - `sso_connection_id` string, nullable: SSO connection id (`sso_…`), or null to unlink.

## 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
  - `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

## 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)