DNS & Certificates

Serving a site at a domain you own has two parts: point the domain at the edge, and prove you own it. TLS is automatic once ownership is verified — certificates are issued via ACME (the same protocol behind Let's Encrypt).

1. Point your domain at the edge

Add a CNAME at your DNS provider pointing your domain at your YourSpace site subdomain:

Type   Name              Value
CNAME  your-site.com     your-site.yo.urspace.net

Apex domains (no subdomain) can't use CNAME in standard DNS. Some providers offer ALIAS, ANAME, or CNAME flattening as equivalents; others don't. Check your provider's docs.

2. Claim the domain

Tell YourSpace you intend to serve the domain. The server responds with a one-time verification token and the DNS record you need to publish:

$ curl -X POST https://api.yo.urspace.net/v1/sites/my-site/domains \
    -H "Authorization: Bearer $YOURSPACE_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"domain": "your-site.com"}'

{
  "domain": "your-site.com",
  "token": "ys-verify-9F3aK7pQrX2bV8mN1",
  "txt_record": "_yourspace-verify.your-site.com"
}

The claim reserves the binding under your site. It is not active until verification succeeds.

3. Publish the TXT record

Add a TXT record at the location the claim response returned:

Type  Name                                  Value
TXT   _yourspace-verify.your-site.com       ys-verify-9F3aK7pQrX2bV8mN1

DNS changes usually propagate within a few minutes. The TXT record proves you control the domain's DNS — without it, YourSpace will not serve traffic on your hostname or attempt to issue a certificate.

Entering the Name field. Many DNS providers may expect the Name field as a relative prefix — _yourspace-verify rather than the fully qualified _yourspace-verify.your-site.com — and append your zone automatically. Entering the fully qualified form typically places the record at _yourspace-verify.your-site.com.your-site.com without any UI warning, and verification will fail. Enter the prefix alone, or add a trailing dot (_yourspace-verify.your-site.com.) to mark the name as already fully qualified per DNS convention. The same applies to the CNAME in step 1. If unclear, confirm the record with dig TXT _yourspace-verify.your-site.com before retrying.

4. Verify

Once the record is live, ask YourSpace to check it:

$ curl -X POST https://api.yo.urspace.net/v1/sites/my-site/domains/your-site.com/verify \
    -H "Authorization: Bearer $YOURSPACE_TOKEN"

{"verified_at": "2026-04-19T20:14:07Z"}

On success, the binding activates: the edge begins routing traffic for your domain to your site, and an ACME certificate is issued automatically.

If the TXT record is missing or the token doesn't match, the API returns 412 with diagnostic detail so you can correct the record and retry.

5. Multiple subdomains

Serving several hostnames under one domain (for example example.com, www.example.com, blog.example.com) works today: bind and verify each one with its own claim → TXT → verify cycle. Each gets its own binding, TXT proof, and certificate.

6. Bring your own certificate

If you need a specific certificate — EV, wildcard, or an internal CA — specify it in yourspace.yml:

tls:
  auto: false
  cert: ./certs/my-cert.pem
  key:  ./certs/my-key.pem

YourSpace serves your certificate and skips ACME provisioning. You're responsible for renewal in this mode.

7. After verification

Leave the TXT record in place for as long as the domain is bound. It is the proof of control, and keeping it published means a planned periodic re-verification check (which re-resolves the record on a schedule and suspends a binding whose proof has disappeared) won't disrupt your site once it ships. Removing the record early forfeits that safety margin.

To confirm your certificate is active after verification:

$ curl -vI https://your-site.com 2>&1 | grep "subject:"
*  subject: CN=your-site.com