Custom domains

Your app is reachable at <slug>.substrio.com and at each domain you attach using your app key. Attach domains one at a time.

Attaching a domain

curl -X POST "$SUBSTRIO_URL/v1/_tenant/domains" \
  -H "X-Substrio-Tenant: my-app" -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "mail.example.com"}'

The domain attaches immediately and the response is 200 with {"domain", "status": "attached"}. Attachment requires no record to publish and performs no DNS lookup. Point the domain's DNS at your app, using a CNAME to my-app.substrio.com or a proxy such as Cloudflare, to serve traffic there.

Attaching or detaching also works through the MCP tools substrio_tenant_domain_attach and substrio_tenant_domain_detach.

Certificate issuance starts when the domain attaches. Exact names use HTTP-01; *. domains use DNS-01. If DNS does not yet point at your app, the check fails. The request is retried after 1 hour, then 2, 4, and so on up to every 24 hours, and at each 12-hour recheck. The first successful check after DNS points to the app issues the certificate.

Example, with the app's own key:

curl -X POST "$SUBSTRIO_URL/v1/_tenant/domains" \
  -H "X-Substrio-Tenant: shop" -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "shop.example"}'
# {"domain": "shop.example", "status": "attached"}

With shop.example pointing at your app, https://shop.example/ is the app.

The first app to attach a domain holds it. An attempt to attach the same name to a second app returns 409. This operation does not move the domain between apps.

Listing and detaching

curl "$SUBSTRIO_URL/v1/_tenant/domains" \
  -H "X-Substrio-Tenant: my-app" -H "Authorization: Bearer $SUBSTRIO_KEY"
# {"domains": [{"domain": "mail.example.com", "status": "attached"}]}

curl -X DELETE "$SUBSTRIO_URL/v1/_tenant/domains/mail.example.com" \
  -H "X-Substrio-Tenant: my-app" -H "Authorization: Bearer $SUBSTRIO_KEY"
# 204, or 404 when the app does not hold it

Certificates in place

An issued or renewed certificate is served from the next handshake. Handshakes already in progress finish with the certificates they started with. Those certificates are freed after no handshake can read them.

CLI

substrio domains add mail.example.com      # attached at once
substrio domains list
substrio domains remove mail.example.com