# Your own domain Referral links on go.example.com and your partner portal on partners.example.com: every DNS step, what each domain serves, and removing one. 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/` 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 | Kind | Example | What it serves | |---|---|---| | `links` | `go.example.com` | Your partners' links (`/`), the in-app panel (`/r/embed/`: set the loader's `origin` to this domain), and `/`, which sends visitors to your product when the domain serves one program | | `portal` | `partners.example.com` | Your partner portal and join pages, and everything a links domain serves | 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: | Type | Name | Value | |---|---|---| | TXT | `_boltclaw.go.example.com` | `bc-verify=` followed by the token shown for your domain | 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. ```bash 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 | `status` | Meaning | |---|---| | `pending_ownership` | Waiting for the TXT record | | `pending_dns` | Waiting for the CNAME record | | `pending_certificate` | The certificate is being issued | | `active` | Answering | | `detached` | Its records stopped pointing at us, so it stopped answering | `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](https://boltclaw.ai/docs/referral-portal).