Skip to content

Prove domain ownership

TrustNet registers production RPs instantly, without a review step. To make that safe, you must prove that you control the registrable domain (eTLD+1) of every production redirect host.

What is proven

  • The unit is the registrable domain, not the full hostname. Proving example.com covers app.example.com and login.example.com.
  • The proof is account-scoped: one verified domain serves every tenant and RP your account owns.
  • Loopback hosts (localhost, 127.0.0.1, [::1]) are exempt only for a local development RP, which cannot publish DNS records.

Prove a domain in the portal

  1. In the registration form, add your production redirect URIs. The form derives the registrable domain of each host and requests a proof.
  2. Publish the token as a DNS TXT record:

_trustnet-verify.example.com TXT <token>

Use the exact name and token shown by the portal. The record name is the _trustnet-verify. label followed by the registrable domain. 3. Wait for DNS propagation, then press Verify.

A verified domain is marked with a check and the registration can proceed.

The .well-known alternative

The management API can issue a proof with method well_known instead of dns_txt. In that case, serve the token as plain text at:

https://example.com/.well-known/trustnet-client-verification

The response must be 200 with the token as the body (short plain text, not HTML). Then verify the proof. The portal registration form creates DNS TXT proofs; use the API if you need the .well-known method.

Automating proofs

The portal uses the RP management API:

Action Endpoint
List proofs GET /api/v1/rp/domains
Issue a proof POST /api/v1/rp/domains with {"registrable_domain":"example.com","method":"dns_txt"}
Verify POST /api/v1/rp/domains/{domain_id}/verify

These are first-party portal endpoints: they use your portal session, require AAL2 and a fresh step-up, and state-changing calls require the portal's CSRF header. They are not called with an RP client secret.

Canonicalization rules

  • Domains are lowercased and stripped of a trailing dot.
  • The proof is for the eTLD+1 (for example, app.example.co.uk → example.co.uk).
  • Non-ASCII hosts are rejected rather than punycoded. Use the ASCII/punycode form (xn--…) if your domain is internationalized.
  • IP literals are not registrable, except loopback hosts under local development.

Troubleshooting

  • Verify returns pending — DNS has not propagated yet, the record is at the wrong name, or the token differs. Check the exact record name and value.
  • One proof is reused — that is expected: verification is per registrable domain, so a second host under the same domain is already covered.
  • A proof lapses — the host is no longer verified, so registration or configuration changes that require it are refused until you re-verify. If the RP was suspended, reinstate it after re-verifying. Re-verification is idempotent and safe to repeat.
  • Local development with a non-loopback host is refused — the local development switch is not a verification bypass. Untick it and prove the domain, or use a loopback host.