Search Log in Get started free
Get started

Custom domains

Put your links on a subdomain you own, such as `links.yourcompany.com`. You add three DNS records; we issue the HTTPS certificate and serve your app's link files on it.

  • Links
On this page 7
  1. Before you start
  2. 1. Add the domain
  3. 2. Add three DNS records
  4. 3. Wait for Live
  5. 4. Open your app from the new domain
  6. Remove a domain
  7. Limits

Before you start

  • Plan: custom domains are part of Scale and Enterprise. On other plans the API answers 402 plan_required.
  • How many: up to 5 per workspace.
  • Which name: a subdomain you don't use for anything else, like links.yourcompany.com or go.yourcompany.com. A bare domain (yourcompany.com) can't be used, because a CNAME can't sit on it. Our own domains and IP addresses are refused.
  • Who: owners, admins and members can add and remove domains; viewers can see them.

Your links keep working on <handle>.strait.link the whole time. A custom domain is an extra name for the same links.

1. Add the domain

In Dashboard → Settings → Custom domains, type the subdomain and press Add domain. Or from your server, with the secret key:

Terminal
curl -X POST https://strait.link/v1/domains \
  -H "Authorization: Bearer st_live_…" \
  -H "Content-Type: application/json" \
  -d '{"hostname":"links.yourcompany.com"}'

The answer lists the exact records to add. Reference: Add a custom domain.

2. Add three DNS records

At your DNS provider, add the three records the dashboard shows, copied exactly (each has a copy button):

Type Name Value What it's for
CNAME links.yourcompany.com fallback.strait.link Sends your links to Strait
TXT _cf-custom-hostname.links.yourcompany.com a value made for your domain Proves you own the domain
TXT _acme-challenge.links.yourcompany.com a value made for your domain Lets us issue its HTTPS certificate

Both TXT values are new each time a domain is added, so always copy them from the dashboard or the API answer. If your DNS is on Cloudflare, set the CNAME to DNS only (grey cloud).

3. Wait for Live

The dashboard checks the domain every 15 seconds while the page is open. Its status moves on by itself:

Status What it means What to do
Waiting for DNS We can't see the records yet Add them. DNS changes can take a few minutes to an hour to show up
Issuing certificate DNS is right; the HTTPS certificate is being issued Wait, usually a few minutes
Live Your links work on this domain, with HTTPS Nothing
Needs attention Something is wrong; the card shows the message from our certificate provider Check every record matches exactly, then wait a few minutes

A domain goes Live only when the certificate is issued and the ownership TXT record is in your DNS. A CNAME alone is never enough, so a domain someone else once pointed at us can't be claimed without its owner's DNS. In the API, status is pending_dns, issuing_certificate, live or problem (plus not_created and unknown); see List custom domains.

4. Open your app from the new domain

Once the domain is live, we serve your app's link files on it too (/.well-known/assetlinks.json and /.well-known/apple-app-site-association). For links on it to open your app instead of the browser, add the domain to your next app build:

  1. Android: another <data android:host="links.yourcompany.com" /> in your App Links intent filter (the one with android:autoVerify="true").
  2. iPhone: another Associated Domains entry, applinks:links.yourcompany.com.
  3. SDK: add links.yourcompany.com to linkHosts in the SDK config, so the SDK treats links on it as yours.

Once a domain is live, shortUrl in API answers uses it, and the dashboard copies links on it. Links you shared before keep working on <handle>.strait.link.

Remove a domain

Press Remove on the domain's card, or call Remove a custom domain (DELETE /v1/domains/{hostname}). Links shared on that domain stop working right away; the same links keep working on <handle>.strait.link.

Then delete its DNS records at your DNS provider: the CNAME and both TXT records. We stop serving the domain either way, but a CNAME left pointing at us is a record you don't need.

Closing a workspace also removes its custom domains from our certificate provider. The names stay reserved for that workspace until it's deleted for good, 30 days later.

Limits

Status reads are limited to 20 at once, then 1 every 2 seconds, per workspace. Adds and removes together: 10, then 1 every 6 minutes. Details: Rate limits.