# Remove a custom domain

`DELETE /v1/custom-domains/{custom_domain_id}` · permission `custom-domains:write`

Removes a custom domain: it becomes `released`, sign-in on it stops and the name stays quarantined for 30 days (no other environment can add it). The primary domain and the domain used as the environment's issuer cannot be removed; make another domain primary first. Removing an already released domain only repeats the release in the platform registry.

## Request

| Field | Type | Required | Description |
|---|---|---|---|
| `custom_domain_id` | string | yes | Custom domain ID (`cdom_…`). |
| `If-Match` | header | yes | Required. The domain's `ETag`; `428` when missing, `412` when it does not match. |

No request body.

## Response

`204 No Content`.

## Errors

| HTTP | code | When |
|---|---|---|
| 404 | `not_found` | The custom domain does not exist or belongs to another environment. |
| 409 | `custom_domain_in_use` | The domain is the primary domain or the environment's issuer. |
| 409 | `domain_in_use_by_rp_id` | The domain is the passkey rpId of a connection, or the previous rpId of a running rpId migration; move the rpId with [Change the passkey rpId](../connections/change-rp-id.md) first. |
| 412 | `precondition_failed` | `If-Match` does not match the domain's current version. |
| 428 | `precondition_required` | `If-Match` is missing. |
| 503 | `service_unavailable` | The platform domain registry or the environment's issuer information is temporarily unavailable. |
| 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. |

## Example

```bash
curl -X DELETE https://api.eu.keenauth.com/v1/custom-domains/cdom_01j9xk3m7q8r2s4t6v8w0y2z4a \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H 'If-Match: "3"'
```