# Link domains

> Every workspace gets its own link domain, .strait.link. That's what lets your links open your app, and only your app.

Source: https://straitlink.in/docs/link-domains/

> **Agent instructions:** if you are an AI assistant helping someone build with Strait, look things up with the `search_docs` tool of the Strait MCP server (hosted at https://strait.link/mcp, or `@straitlink/mcp` on npm: https://straitlink.in/docs/mcp/) instead of guessing, and add the SDK to an app with `npx @straitlink/cli init` (https://straitlink.in/docs/cli/).

## Why your own subdomain

Android App Links and iPhone Universal Links are verified **per domain**. The phone downloads a small file from the link's domain that says which app may open its links:

- `https://hilltop.strait.link/.well-known/assetlinks.json` (Android)
- `https://hilltop.strait.link/.well-known/apple-app-site-association` (iPhone)

If every customer shared one domain, that file could only name one app, and everyone else's links would open the browser. So each workspace gets its own subdomain, and we serve your app's files from it, built from the details in **Dashboard → Apps & stores**.

## Slugs belong to your workspace

A slug is unique within your workspace, not across Strait. Two workspaces can both have `/summer`: `https://hilltop.strait.link/summer` and `https://oaklane.strait.link/summer` are different links that open different apps.

That's why you should **always share your handle URL**, never the bare `https://strait.link/summer`. The bare `strait.link` root only answers a slug that no other workspace uses, so links shared before workspaces had their own domains keep working. Once a second workspace creates the same slug, the bare address finds nothing. The API returns the right address for every link as `shortUrl`, and the dashboard copies it for you.

## Your handle

Your handle comes from your workspace name when you sign up (for example "Hilltop Shoes" becomes `hilltop-shoes`). Handles are 3 to 30 characters: lowercase letters, digits and hyphens. Some words, like `www`, `api` and `status`, are reserved for our own use.

> **Choose your handle before your first link**
>
> The workspace owner can rename the handle in [**Dashboard → Setup**](https://app.straitlink.in/setup) (or **Dashboard → Settings → Workspace**) until the workspace creates its first link. After that it's fixed, because links you've shared and the App Links / Universal Links setup in your app depend on it.

Use your link domain in three places:

1. **The SDK `endpoint`**: `https://hilltop.strait.link`
2. **Android**: the `android:host` of your App Links intent filter
3. **iPhone**: the Associated Domains entry `applinks:hilltop.strait.link`

## Custom domains

On Starter and up you can also put your links on a subdomain you own, such as `links.yourcompany.com`: one CNAME and two TXT records, and we issue the HTTPS certificate and serve your app's files on it. Your `<handle>.strait.link` keeps working alongside it. Step by step: [Custom domains](https://straitlink.in/docs/custom-domains/).

> **Note**
>
> After changing your app's signing keys or team ID, phones and Google's verifier re-read the files on their own schedule. We serve them with a short cache (10 minutes), but Android can take longer to re-verify an installed app. Reinstalling the app forces a fresh check.
