Verify domain ownership

A frontend serves a custom domain only for the account that owns it. Verify a domain once with a DNS TXT record, and your account owns it and every name below it. You can then attach example.com, app.example.com, or staging.app.example.com to any frontend in any of your projects, with managed or BYOC TLS, without another record.

curl -X POST "https://api.volcano.dev/user/domains" \
  -H "Authorization: Bearer $PLATFORM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com"}'

Verify a domain

1. Request verification. Until DNS serves your record, Volcano answers 409 Conflict with the record to publish:

   {
     "error": "ownership of example.com is not verified",
     "code": "ownership_verification_required",
     "required_record": {
       "name": "_volcano.example.com",
       "type": "TXT",
       "value": "volcano-domain-verification=6f0d3c1b9e2a47d58c4b1a0e9f3d2c7b"
     }
   }

2. Publish the record with your DNS provider:

   _volcano.example.com.  TXT  "volcano-domain-verification=6f0d3c1b9e2a47d58c4b1a0e9f3d2c7b"

3. Repeat the request. Volcano returns 201 Created:

   {
     "domain": "example.com",
     "verified_at": "2026-10-07T14:03:11Z"
   }

   A domain your account already owns returns 200 OK.

Publish the record at the name itself. Volcano ignores a TXT record reached through a CNAME, including a wildcard CNAME, because the CNAME's target may belong to someone else.

The value depends on your account and the domain, so it proves nothing for another account or another domain. It stays the same until Volcano rotates the key it is derived from. A rotation never removes a verified domain from your account, and both the old and the new value prove ownership while it is under way. After it finishes, only the new value counts: Volcano returns it as required_record the next time a request needs a proof.

You can also skip this step. Attaching a hostname that nobody owns returns the same 409 and required_record, for the hostname's registrable domain: example.com for app.example.com, and example.co.uk for app.example.co.uk. A managed TLS domain instead reserves the hostname and reports the record in verification_records; the reservation proceeds once the record is published. See Custom domains.

Verify a subdomain

Verify a subdomain such as team.example.com when only that part of your DNS is yours to change. The most specific verified domain owns a hostname, so another account that verifies team.example.com owns app.team.example.com, while app.example.com stays with whoever verified example.com. Only whoever runs the example.com zone, or a zone delegated from it, can publish _volcano.team.example.com, so the zone's operator decides who owns the subdomain.

Volcano refuses public suffixes such as com, co.uk, or github.io, where names belong to unrelated owners.

List and remove verified domains

curl "https://api.volcano.dev/user/domains" \
  -H "Authorization: Bearer $PLATFORM_TOKEN"

{
  "domains": [
    { "domain": "example.com", "verified_at": "2026-10-07T14:03:11Z" }
  ]
}

curl -X DELETE "https://api.volcano.dev/user/domains/example.com" \
  -H "Authorization: Bearer $PLATFORM_TOKEN"

Removing a domain returns 204 No Content. Custom domains already attached below it keep serving; attaching another one needs a new verification. Closing your account removes its verified domains.

Move a domain to another account

A domain moves when DNS changes hands, such as after a sale or when a team consolidates accounts. The new account publishes its own _volcano record and verifies the domain. Volcano moves the domain only when DNS serves the new account's record and no longer serves the old one:

A record counts as the old account's only while its value is current. After a key rotation finishes, a record with the previous value no longer blocks a move, so a new account that publishes its own record in the zone takes the domain.

Custom domains the old account already attached keep serving until it removes them. While the lookup of the old account's record fails, Volcano answers 503 Service Unavailable instead of guessing; retry later.

Volcano's own domains

Volcano owns its own domains, including volcano.dev and volcano.run. No account can verify them or attach a hostname below them.

Errors