---
title: "Prove domain control (two-phase DNS TXT)"
method: POST
path: "/api/agents/verify-domain"
tags: ["agents"]
---

# Prove domain control (two-phase DNS TXT)

`POST /api/agents/verify-domain`

## Request

- Base URL: `https://api.depixapp.com`
- URL: `https://api.depixapp.com/api/agents/verify-domain`
- Auth: none required

Unlocks receiving from third parties AND, for an agent account, the merchant tools — the domain proof stands in for the document round trip a human does. Authentication is the agent keypair scheme (signed X-Agent-* headers), not a Bearer key. Phase 1 ({domain}) returns the TXT challenge to publish at _depix-verify.<domain>; phase 2 ({domain, confirm: true}) resolves it and records agents.verified_domain (the registrable eTLD+1). The challenge value is stable — re-fetch it any time.

## Request body

- VerifyDomainRequest: Two-phase domain proof. Phase 1 ({domain}) returns the DNS TXT challenge; phase 2 ({domain, confirm: true}) resolves the TXT and records the verified domain.
  - `domain` string, required: The domain to verify — normalized to its registrable eTLD+1 ("shop.acme.com.br" → "acme.com.br"). URL-ish input tolerated.
  - `confirm` boolean: Set true for phase 2: resolve the TXT record and confirm. Omit/false for phase 1: obtain the challenge.

## Response `200`

Phase-1 challenge or phase-2 confirmation.

- union: Phase 1 returns the challenge to publish; phase 2 returns the verified domain.
  - object: Phase-1 challenge: create this DNS TXT record, then call again with confirm: true.
    - `record_name` string, required: TXT record name to create (_depix-verify.<domain>).
    - `record_value` string, required: Exact TXT record value (depix-verify=<token>). Stable across calls — safe to re-fetch.
  - object: Phase-2 confirmation: the domain is now verified for this agent.
    - `verified_domain` string, required: The registrable domain (eTLD+1) recorded on the agent.
    - `verified` boolean, required: Whether the proof also unlocked the merchant tools (checkouts and products) on this account. For an agent the domain proof IS the account verification, so this is normally true. It can be false while the account is suspended — the domain proof itself is recorded either way. Read GET /api/verification for the current state.

## Other responses

- `400`: Malformed domain.
- `401`: Signature chain failed or the public key is not a registered agent (agent_unknown_key).
- `403`: Account blocked.
- `422`: TLD outside the allowlist (domain_tld_not_allowed with details.allowed_tlds), free-subdomain host (domain_free_host), or the TXT record is missing/mismatched (domain_txt_not_found).
- `429`: Rate limited (per-IP, per-key or per-merchant window). Retry after `retry_after` seconds (also in the Retry-After header).
- `503`: Nonce anti-replay store unavailable — the signature guard fails CLOSED; retry.

---

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