---
title: "Verify domain"
method: POST
path: "/v2/domains.verifyDomain"
tags: ["domains"]
---

# Verify domain

`POST /v2/domains.verifyDomain`

Restart verification for a custom domain.

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

Call this after you correct the DNS records of a domain that shows `failed`, or to give a
`pending` domain a new 24-hour verification period. The domain goes back to `pending` and
the 24-hour period starts again.

The endpoint returns when Unkey accepts the retry. Poll `domains.getDomain` for the result.

A domain that is already `verified` returns a 412.

**Required Permissions**

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

## Request body

- V2DomainsVerifyDomainRequestBody
  - `domain` string, required — Identifies a domain by its name or by its ID. Send the fully qualified domain name, such as 'api.acme.com', without a scheme, port, or path, or send the domain ID that domains.createDomain returns. You can send an internationalized name in Unicode or in Punycode form. Both forms address the same domain.

## Response `202`

Verification retry accepted. The workflow runs in the background.

- V2DomainsVerifyDomainResponseBody
  - `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 only lacks `environment.*.verify_domain` receives a 404 instead.
- `404` — Not Found - The domain does not exist in your workspace, or it was deleted, or your root key is not permitted to verify it.
- `412` — Precondition Failed - The domain is already verified. There is nothing to retry.
- `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)