---
title: "Delete domain"
method: POST
path: "/v2/domains.deleteDomain"
tags: ["domains"]
---

# Delete domain

`POST /v2/domains.deleteDomain`

Delete a custom domain from your workspace.

Address the domain by its id or by its name. Names are unique per workspace, so
`api.acme.com` is enough.

Unkey stops serving the domain. Later requests fail with a certificate error. The DNS
records at your provider stay in place.

**Required Permissions**

Your root key must have one of the following permissions:
- `environment.*.delete_domain` (to delete domains in any environment)
- `environment.<environment_id>.delete_domain` (to delete domains in a specific environment)

## Request body

- V2DomainsDeleteDomainRequestBody
  - `domain` string, required — Identifies a domain by its Unkey ID or by its name. Pass a 'dom_'-prefixed ID, or a fully qualified domain name such as 'api.acme.com' without a scheme, port, or path. You can give an internationalized name in Unicode or Punycode form. Both forms address the same domain. Domain names are unique per workspace, so the name alone addresses the domain. You do not need to supply a project, app, or environment.

## Response `200`

Successfully deleted the domain.

- V2DomainsDeleteDomainResponseBody
  - `meta` Meta, required — Metadata object included in every API response. This provides context about the request and is essential for debugging, audit trails, and support inquiries. The `requestId` is particularly important when troubleshooting issues with the Unkey support team.
    - `requestId` string, required — A unique id for this request. Always include this ID when contacting support about a specific API request. This identifier allows Unkey's support team to trace the exact request through logs and diagnostic systems to provide faster assistance.
  - `data` EmptyResponse, required — Empty response object by design. A successful response indicates this operation was successfully executed.

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `403` — Forbidden - The root key or its workspace is disabled. A root key that simply lacks `environment.*.delete_domain` receives a 404 instead, so permissions cannot be used to discover which domains exist.
- `404` — Not Found - The domain does not exist in your workspace, it was already deleted, or your root key may not delete it.
- `429` — Too Many Requests
- `500` — Internal server error

---

[API](https://skmtc.net/unkeyed/apis/unkey-api.md) · [All operations](https://skmtc.net/unkeyed/apis/unkey-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/unkeyed/unkey-api/revisions/d3689bca6458/schema)