Bring Your Own Domain

By default an identity is named under the shared identity zone. Delegate a domain you already own and the same identities are minted under your apex instead, so a counterparty who checks an address sees your brand in the name rather than Whisper's.

The delegation is the authorisation. There is no token to paste and no TXT challenge: publishing the nameservers and the matching DS at your registrar is the proof that you control the name, because only the domain's owner can do it.

1. Ask for the record set

Send the domain with action set to submit. The call answers with every record you have to publish.

curl -s https://graph.whisper.online/api/query \
  -H "X-API-Key: <your key>" \
  -H "content-type: application/json" \
  --data-binary @- <<'JSON'
{"query": "CALL whisper.agents({op: 'domain', args: {op: 'submit', name: 'agents.example.com'}})"}
JSON

The result is a list of kind and value pairs:

{
  "columns": ["op", "ok", "status", "result", "error", "retry_after", "elapsed_ms"],
  "rows": [
    {
      "op": "domain",
      "ok": true,
      "status": 200,
      "error": null,
      "result": {
        "columns": ["kind", "value"],
        "rows": [
          ["state", "pending"],
          ["name", "agents.example.com"],
          ["record", "agents.example.com. NS ns1.whisper.online."],
          ["record", "agents.example.com. NS ns2.whisper.online."],
          ["record", "agents.example.com. DS <key tag> 13 2 <digest>"],
          ["record", "agents.example.com. CDS <key tag> 13 2 <digest>"],
          ["record", "agents.example.com. CDNSKEY 257 3 13 <public key>"],
          ["caa", "agents.example.com. CAA 0 issue \";\""],
          ["caa", "agents.example.com. CAA 0 issue \"whisper.online\""],
          ["note", "<guidance for this submission>"]
        ]
      }
    }
  ]
}

The signing key is derived deterministically per domain, and both nameservers compute it independently. That is why the DS stays stable if the zone is ever re-provisioned, and why you only ever publish it once.

2. Publish the delegation at your registrar

In your registrar's zone for the parent name, publish two records and nothing else:

• the two NS records, exactly as returned, with no glue addresses
• the DS record, algorithm 13 with digest type 2

The submission also returns the digest-type-4 form, for a registrar that requires it. Publish one DS, not both.

The CDS and CDNSKEY records are served inside the delegated zone by Whisper, not published by you. They exist so that a registrar supporting automated DNSSEC maintenance can pick the key up and keep it current on its own.

Publish the two CAA records at the same time. Together they say that no certificate authority may issue for this name except the one Whisper runs for identity leaves, which is what keeps the DANE pin the only path to a certificate under your apex.

3. Wait for the observation, then read the state

Whisper watches the delegation from several vantage points and attaches the domain only when four things hold together: the parent delegates to both nameservers, the DS is present and matches the zone's key, the DNSSEC chain validates end to end, and every vantage point agrees.

curl -s https://graph.whisper.online/api/query \
  -H "X-API-Key: <your key>" \
  -H "content-type: application/json" \
  --data-binary @- <<'JSON'
{"query": "CALL whisper.agents({op: 'domain', args: {op: 'status', name: 'agents.example.com'}})"}
JSON

Read the state row. It stays pending until the observation succeeds, and the note rows say which of the four conditions is still outstanding. Registrar changes take a while to reach the parent zone, so re-read rather than re-submit.

4. Confirm the chain from outside

Once the state has moved on, check the delegation the way a stranger would. The DS at the parent and the DNSKEY in the zone have to agree, and the answer has to come back authenticated.

dig +short NS agents.example.com
dig +dnssec DS agents.example.com
delv agents.example.com NS

delv prints fully validated when the chain holds from the root down. That is the same check the observation runs, taken from your own vantage point.

5. Mint an identity under your name

Nothing about minting changes. The derivation is unchanged, and the handle is still a function of the address; only the zone the name sits in is different, so an identity is now a<handle>.agents.example.com. Create one exactly as in Create an Identity, then read it back:

dig -x <the new address> +short
# a<handle>.agents.example.com.

The address itself stays in Whisper's space, because that is what makes it routable and what the registry answers for. The name is yours. The registry object names you as the operator of record, which is what an abuse desk or a SIEM lands on when it looks the address up.

Withdrawing

Remove the NS and DS records at your registrar and the delegation ends. Whisper serves RFC 8078 delete sentinels inside the zone as part of that teardown, so a registrar that maintains DNSSEC automatically retires the DS on its own. Identities already minted under the name stop resolving when the delegation goes, so revoke or re-home them first.

For the full argument and column reference, see Manage a Domain.