> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect a custom domain for short links

> Provision DNS and TLS for a branded short-link host, verify the /l/:code redirect on it, save it under Settings → General, and confirm new links mint on your domain.

# Connect a custom domain for short links

By default Orbit mints short links on `https://api.orbit.devotel.io`. A branded host such as `https://go.yourbrand.com` puts your own domain in front of every recipient instead. This guide walks the full setup: DNS, TLS, a redirect check, the tenant setting, and a test mint.

The long-form behaviour reference (resolution order, click analytics, failure modes) lives in [Short links with click tracking, §4](/guides/short-links-and-click-tracking#4-branded-short-domains). This page is the setup checklist.

## 1. When to use a branded domain

Recipients tap a link that carries your brand instead of a platform host. If your email already authenticates as `yourbrand.com` (DKIM, Return-Path), a `go.yourbrand.com` short link keeps the domain story coherent across channels, and recipient trust follows coherence: the same brand in the message and in the link.

Set one when you send tracked links at volume and you control the domain's DNS. Stay on the platform default when you only mint the occasional link; the default needs no setup and resolves everywhere.

## 2. Pick a host shape

The setting accepts a bare `https://` host only, for example `https://go.yourbrand.com`. The save-time validation and the server that mints links enforce the same rule:

* `https://` required in production (`http://` is accepted for staging vanity hosts only).
* No path, query, or fragment: `https://go.yourbrand.com`, not `https://go.yourbrand.com/landing`. Orbit appends `/l/:code` itself.
* A trailing slash is stripped silently on save.

Use a subdomain you own and can delegate; `go.`, `link.`, and `t.` are common choices. The apex is not required.

## 3. Provision DNS

Add one CNAME record at your DNS provider:

| Record | Type | Value |
| - | - | - |
| `go.yourbrand.com` | CNAME | `api.orbit.devotel.io` |

`api.orbit.devotel.io` is Orbit's redirector: it serves the public `GET /l/:code` route your short links resolve through. If your onboarding contact handed you a dedicated redirector host, use that value instead.

Wait out the record's TTL before moving on. A CNAME that has not propagated reads as a missing host in every later step.

## 4. TLS

Recipients fetch short links over HTTPS only, so the host needs a valid certificate before any link mints on it. Orbit provisions the managed certificate for your host once the CNAME resolves, and your ops contact confirms issuance. Until then, requests to your host fail at the TLS handshake, which is exactly what the next step distinguishes from a routing problem.

Keep the CNAME in place after issuance. A record removed mid-provisioning is the usual cause of a stalled certificate.

## 5. Verify the redirect path

Probe the route with a code that does not exist:

```bash theme={null}
curl -sS -w "\n%{http_code}\n" https://go.yourbrand.com/l/TEST00
```

The healthy answer is an HTTP 404 with Orbit's JSON error body, not a DNS failure or a TLS handshake error. The 404 proves DNS resolves, the certificate is valid, and the `/l/:code` route answers on your host. A real code returns a 3xx redirect whose `Location` header points at the target URL; `curl -sSL` follows it to your landing page.

## 6. Set the tenant field

Open **Settings → General** and find the *Branded short-link domain* card. Paste the bare host (`https://go.yourbrand.com`) and **Save**. The card validates before writing and shows one of these inline messages when a value cannot be saved:

* `Enter a full URL with a scheme, e.g. https://go.acme.li.` when the scheme is missing or unparsable.
* `Must start with https:// (http:// is allowed for staging vanity domains only).`
* `URL must include a host.`
* `Use a bare host with no path, query, or fragment (e.g. https://go.acme.li).` when the value carries a path, query, or fragment.
* `Domain is too long (max 256 characters).`

On success the card shows a **Short links use:** badge with your host. **Reset to default** clears the value, with a confirmation, and returns future mints to the platform host. Saving a blank field clears it too.

## 7. Mint a test link and confirm

```bash theme={null}
curl -sS -X POST https://api.orbit.devotel.io/api/v1/links/ \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://www.yourbrand.com/landing" }'
```

The `201 Created` response carries `short_url`. Confirm its host is your domain:

```json theme={null}
"short_url": "https://go.yourbrand.com/l/gH4kM2"
```

Then follow it on your host:

```bash theme={null}
curl -sSI https://go.yourbrand.com/l/gH4kM2
```

Expect a 3xx with `Location: https://www.yourbrand.com/landing`. Every mint path honors the setting from the moment it is saved: one-off API mints, the compose dialog's shorten preview, and auto-shortened sends. Links minted before the change keep resolving on their original host.

## 8. If links still mint on the default host

An invalid saved value never blocks a send. Minting falls back to `https://api.orbit.devotel.io` and writes a warn-level log line against the setting, so the misconfiguration is findable in your log trail. If links mint on the platform host despite a saved value, the stored host almost certainly carries a path or fragment; re-open the card, correct the value, save, and re-mint. Existing short URLs keep resolving either way.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.