Use auth.yourdomain.com instead of rootherald.io
When it ships, custom domains will let you add a CNAME, validate an ACM cert, and point your server client at a branded base URL. Your domain would then show in your server's egress and on the portable-token issuer instead of rootherald.io. (In the default Background-Check flow only your server calls Root Herald; the user's device never does.)
Custom-domain provisioning is on the roadmap and not available today. Every tenant runs on the default rootherald.io edge for now — point the SDK at rootherald.io (see direct mode). The walkthrough below describes how the flow will work once the domain orchestrator is production-ready; the dashboard wizard, ACM issuance, and pricing are not switched on yet.
When it launches, custom domains are planned as a $49/month add-on on Pro, included in Business and Enterprise, with the Free tier excluded. Until then, point the SDK at rootherald.io.
Pick the subdomain in the dashboard
When the feature ships, you'll navigate to Dashboard → Settings → Custom domain → Add domain and enter the fully-qualified hostname you want (e.g. auth.acme.com). The wizard will print a CNAME target to add to DNS, plus an ACM certificate validation record.
Target CNAME: tenant-domains.rootherald.io
ACM validation CNAME: _a1b2c3d4e5f6789.auth.acme.com.
ACM validation value: _xyz123.acm-validations.aws.
Status: waiting for DNS records (will check every 30s for 24h).Add the DNS records
In your DNS provider, add:
Type: CNAME
Name: auth (or auth.acme.com depending on provider)
Value: tenant-domains.rootherald.io
TTL: 300
Type: CNAME
Name: _a1b2c3d4e5f6789.auth (the unique ACM validation prefix)
Value: _xyz123.acm-validations.aws.
TTL: 300Save. AWS Certificate Manager will pick up the validation record automatically; Root Herald will issue and attach the cert once it succeeds. Expected end-to-end: 3-7 minutes.
Point your server client at the new domain
import { RootHerald } from "@rootherald/node";
// Override the API base so your server's challenge + verify calls land on
// your custom domain instead of api.rootherald.io.
const rh = new RootHerald({
secretKey: process.env.RH_SECRET_KEY!,
baseUrl: "https://auth.acme.com",
});import { verifyAttestationToken } from "@rootherald/node";
// Only if you opted into a portable token (returnToken) or use the badge tier:
// point the issuer at your custom domain — JWKS is fetched from
// `${issuer}/.well-known/jwks.json` unless you override jwksUri.
const verdict = await verifyAttestationToken(token, {
issuer: "https://auth.acme.com",
audience: process.env.RH_PROJECT_ID!,
});Verifying it worked
# DNS resolution and TLS handshake terminate at your domain:
curl -v https://auth.acme.com/health
# The certificate's CN is auth.acme.com, not rootherald.io:
openssl s_client -servername auth.acme.com -connect auth.acme.com:443 < /dev/null \
| openssl x509 -noout -subjectRenewals
ACM certificates auto-renew, so once the feature is live there will be no action required from you. If a renewal ever fails (e.g. you removed the validation CNAME), the dashboard will show a banner 14 days before expiry with a direct link to re-add the record.
The ACM validation CNAME (_a1b2c3d4e5f6789.auth.acme.com) must remain in DNS for the lifetime of the custom domain. AWS uses it for ongoing renewal validation. If you remove it after issuance, the cert won't renew when it expires.