Your own domain

Your referral links and your partner portal can live on a domain of your own: https://go.example.com/jane instead of a BoltClaw address, and your partners' portal at https://partners.example.com, in your brand. Every link keeps working at its https://boltclaw.ai/r/<code> address as well, always.

Adding a domain costs nothing per domain. Each organisation has a number of domains on its plan (5 on Free), and every domain counts from the moment it is added, pending ones included.

Two kinds of domain

A domain serves every program of yours, new ones included, or only the programs you choose. A code of a program the domain does not serve is not found there, so your domain can never be used to send people to anybody else's product. Every page on your domain tells search engines not to index it, and nothing third-party loads on it.

Use a subdomain: go.example.com or partners.example.com. A domain's root (example.com) cannot hold the CNAME record the setup needs, and a wildcard or an IP address is refused.

Adding a domain

Add the domain on Referrals, Brand and domains in the dashboard (you need two-step verification on for this), or with POST /v1/referrals/domains. Its answer, like every read of the domain, lists the exact DNS records still to set, in order, and whether each is in place (records, with type, name, value and done). Set them at your DNS host.

1. Prove the domain is yours. A TXT record:

Until it is seen, nothing else happens: the domain is not added anywhere and serves nothing. The token is your own, so nobody else can claim a domain you control.

2. Point it at us. Once the TXT record is seen, the domain shows its CNAME record: the target our hosting provider recommends for this domain. Use the value shown for that domain and no other: targets differ from domain to domain. If the domain was used with our hosting provider before, a second TXT record appears too; add it as shown.

If your DNS host proxies traffic (an orange cloud, or "proxied"), switch the record to DNS only, or the certificate cannot be issued.

3. The certificate. It is issued for you, usually within minutes of the CNAME record appearing. Two things can hold it up:

• CAA. If your domain has a CAA record, it must allow letsencrypt.org, which issues the certificate. The domain shows caa_warning: true until it does.
• HSTS. If your main site sends Strict-Transport-Security with includeSubDomains, browsers will only open the new domain over HTTPS. Wait until the domain is active before you link to it anywhere.

4. Active. The domain answers, and new links, placements and signup links in the dashboard, the API and the panel use it.

While a domain is pending it is checked every ten minutes for its first hour, then less often; POST /v1/referrals/domains/{id}/check (or Check now) looks at it at once, at most every 15 seconds.

curl https://api.boltclaw.ai/v1/referrals/domains \
  -H "Authorization: Bearer $BOLTCLAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"host": "go.example.com", "kind": "links"}'

An AI assistant always asks you before it adds or removes a domain: both decide where your links and portal answer.

Status

problem says, in a sentence, what is in the way.

When records change, and removing a domain

Every active domain is checked each day. If its TXT or CNAME record is gone twice in a row, the domain is detached: it stops answering, your links answer at their boltclaw.ai/r/ address instead, and the people who manage your referrals are emailed. Put the records back and it reconnects by itself. A domain detached for 7 days is removed (remove_after).

Removing a domain (in the dashboard, or DELETE /v1/referrals/domains/{id}) stops it at once. It is then taken off our hosting provider, so nothing of ours is left pointing at it, and anyone else who controls the domain later can claim it with their own TXT record. Remove your own DNS records for it too.

Your partner portal, the brand it shows and how partners sign in to it are on White-label portal.