Custom domains

Every project already has an address on fortly.com. To serve it at a domain you own as well, you publish two DNS records: a TXT record that proves the domain is yours, and a CNAME that sends its traffic to your project. Fortly checks the first, starts serving the domain, and requests an HTTPS certificate for it. You never buy, upload or renew a certificate yourself.

The examples on this page use a project created as my-app on the account ada, so its name is my-app-ada, and the domain shop.example.com.

Your project's built-in address

A project is served at its name under fortly.com as soon as it exists:

https://my-app-ada.fortly.com

A project's name is its label, the name you chose, joined to your account name. A project created as my-app on the account ada is named my-app-ada. The console shows the address at the top of the project's page, and GET /projects returns it for each project. The name is also what API paths take, such as /projects/my-app-ada/domains. See core concepts.

Names under fortly.com are given out by Fortly, so you cannot add one as a custom domain. Use the built-in address, or add a domain you own.

If you change your account name, the addresses built from it change with it. If a custom domain's CNAME points at the old address, update it to the new one.

The two records

A domain needs both records. They do different jobs, and one does not replace the other. A domain can be verified and still resolve nowhere because its CNAME is missing.

Purpose	Type	Name, as most DNS forms want it	Full name	Value
Prove you own the domain	TXT	`_fortly.shop`	`_fortly.shop.example.com`	`fortly-verify=…` (unique to this domain)
Send its traffic to your project	CNAME	`shop`	`shop.example.com`	`my-app-ada.fortly.com`

The TXT record goes under its own _fortly. name, not at the apex of your domain, so you never need to edit the TXT records that hold your SPF or DMARC settings. Every domain you add gets a different fortly-verify= value. Copy it from the console or from the API response. Do not reuse one from another domain.

Connect a domain

Add the domain

In the console, open the project, go to Domains, enter the hostname, and choose Add domain. Or use the API:

Terminal

curl -X POST https://api.fortly.com/projects/my-app-ada/domains \
  -H "Authorization: Bearer $FORTLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"host": "shop.example.com"}'

JSON

{
  "host": "shop.example.com",
  "verified": false,
  "record_name": "_fortly.shop.example.com",
  "record_value": "fortly-verify=…"
}

The domain is stored as unverified, and it serves nothing yet.

Publish the TXT record

Add the TXT record wherever your domain's DNS is managed. That is not always the company you bought the domain from. The console reads your domain's nameservers and tells you which provider serves your DNS, with a link to it when it recognises the provider.

Most DNS forms want the name relative to your domain, so enter _fortly.shop and paste the fortly-verify=… value. See names in DNS forms if you are not sure which form your provider wants.

Check the record

Choose Check now in the console, or ask the API:

Terminal

curl -X POST https://api.fortly.com/projects/my-app-ada/domains/shop.example.com/verify \
  -H "Authorization: Bearer $FORTLY_TOKEN"

When the record is found, the domain is verified and starts serving straight away:

JSON

{ "host": "shop.example.com", "verified": true, "certificate": "pending" }

If it is not visible yet, you get "verified": false with the record to publish and a why. DNS changes can take a few minutes to reach the resolvers Fortly asks, so wait and check again.

Point the domain at your project

Add a CNAME record for shop whose value is your project's address, my-app-ada.fortly.com. The console shows this record once ownership is proved. GET /projects/my-app-ada/domains returns it as points_to at any time, so you can publish both records together.

Until this record exists, the domain resolves nowhere, even though it is verified.

Wait for HTTPS

Once the domain is verified, Fortly requests a certificate for it. Issuing one usually needs the CNAME in place, so the certificate shows as pending until the domain points here. Then it becomes active, and the console shows the domain as Live.

Names in DNS forms

Nearly every DNS provider wants record names relative to your domain and adds the domain itself. If you paste the full name into such a form, the record ends up as _fortly.shop.example.com.example.com. That name resolves to nothing, and the check keeps saying the record is not visible.

You are adding	Relative name (most providers)	Full name (some providers)
`shop.example.com`	`_fortly.shop`	`_fortly.shop.example.com`
`a.b.example.com`	`_fortly.a.b`	`_fortly.a.b.example.com`
`example.com`	`_fortly`	`_fortly.example.com`

Fortly cannot know where your zone starts. shop.example.com might be a record in example.com or a zone of its own. The console shows the relative form for the most likely reading, which is everything in front of the last two labels, and also gives the full name. The API returns the relative form as record_short in GET /projects/my-app-ada/domains. For a domain like example.co.uk, where the zone has three labels, use the full name or check what your provider shows after you save the record.

Apex domains

DNS does not allow a plain CNAME at the apex of a domain (example.com itself). If your provider offers ALIAS, ANAME or CNAME flattening, use it at the apex with the same value, my-app-ada.fortly.com. If it does not, serve the project at a subdomain such as www.example.com.

A flattened record looks like ordinary addresses from outside, so Fortly cannot see where it points. The console reports this as unknown, not as wrong.

Why an unverified domain serves nothing

A domain is added unverified, and Fortly routes no traffic for it until its TXT record is found. Without that check, anyone could add your domain to their own project, and any of your DNS that still pointed at Fortly would then serve their site. That is how domain takeovers happen.

Each hostname belongs to one project. Adding a hostname that another project already has is refused. The hostname is never moved silently, because that would take a working site off the air.

HTTPS certificates

Proving ownership also requests a certificate for the domain, and it is renewed for you from then on. A failed certificate request never undoes the verification. The domain stays verified and serving either way.

The certificate field on a domain is one of these:

Value	Meaning
`none`	Nothing requested yet. The domain is not verified, or certificates are not issued for it.
`pending`	Requested and not issued yet. This is normal for a minute or two after the CNAME is in place, and it lasts indefinitely if the domain never points here.
`active`	Issued. The domain serves over HTTPS.
`failed`	The certificate could not be issued. Check that both records are still published, then choose Check now. Fortly re-checks a failed certificate when you view the domain, and Check now requests it again.
`external`	The name is proxied through your own Cloudflare zone, and Cloudflare serves HTTPS with your zone's certificate. The console shows HTTPS via your DNS provider.

If your DNS is on Cloudflare and the record is proxied (orange cloud), your site still works. Cloudflare answers with its own certificate, and Fortly does not issue one for a name that is active in another Cloudflare zone. Fortly detects this and reports external rather than failed.

Check a domain's status

GET /projects/my-app-ada/domains lists the project's domains, verified or not, with everything you need to finish setting each one up:

Terminal

curl https://api.fortly.com/projects/my-app-ada/domains \
  -H "Authorization: Bearer $FORTLY_TOKEN"

Field	What it tells you
`verified`	Whether the TXT record has been found.
`record_name`, `record_short`, `record_value`	The TXT record to publish, as a full name, a relative name, and its value.
`points_to`	The value for your CNAME record, which is your project's address.
`pointing`	Where the domain's CNAME goes: `here`, `elsewhere` (usually your previous host), `unknown` (no CNAME visible, as with a flattened apex), `proxied` (through your own Cloudflare zone), or `unchecked` (not verified yet).
`nameservers`	Who serves the domain's DNS, while there is still something to set up.
`certificate`	HTTPS state, as in the table above.

GET /domains lists every domain on your account across all projects, so you can find the one that is not working without opening each project.

Remove a domain

In the console, open the domain's menu and choose Remove domain, or call the API:

Terminal

curl -X DELETE https://api.fortly.com/projects/my-app-ada/domains/shop.example.com \
  -H "Authorization: Bearer $FORTLY_TOKEN"

The domain stops serving at once, and its certificate is released. The response is 204. Then delete the TXT and CNAME records at your DNS provider. If you add the domain again later, you get a new fortly-verify= value to publish.

Limits and accepted names

Custom domains count against your account as a whole, not per project. Pending domains count too. The allowance depends on your plan. See limits.
A hostname needs at least one dot. It uses letters, digits and hyphens, and no part of it can start or end with a hyphen.
Wildcards such as *.example.com are not accepted. Add each name you want to serve.
Hostnames are lowercased, and a trailing dot is dropped.

For every route, its parameters and responses, see the domains API reference.

Troubleshooting

"That record is not visible yet. DNS changes can take a few minutes."

The verify check did not find the TXT record. Check these in order:

The name is right for your provider's form. A record saved as _fortly.shop.example.com.example.com never matches. Look it up from your own machine:
Terminal
```
dig +short TXT _fortly.shop.example.com
```
The value is exactly the fortly-verify=… value for this domain, with no quotes or spaces added by hand.
The record is at the provider that actually serves your DNS. The console names it from the domain's nameservers.

If dig shows the right value, wait a few minutes and choose Check now again.

"could not ask DNS about _fortly.…"

Fortly could not reach a DNS resolver, so it does not know whether your record exists. This comes back as a 502 and is not a statement about your records. Try again shortly.

"… is already pointed at a project"

Another project already has this hostname. If it is one of your projects, or a teammate's, remove it there first, then add it here.

"names under fortly.com are given out by Fortly — add a domain you own"

You tried to add a fortly.com name. Your project already has one, its built-in address. Add a domain you own instead.

"this account has … custom domains, which is all … allows."

Your account has used its custom domain allowance. Remove a domain you no longer serve, or add domain capacity to your plan.

"a domain needs at least one dot" or "wildcards are not accepted here"

Enter a full hostname such as shop.example.com, and add each name separately instead of a wildcard.

The domain shows "Pointed elsewhere"

The domain is verified, but its CNAME points somewhere other than your project. Usually that is the previous host, partway through a move. Change the CNAME's value to the points_to address.

"The certificate did not issue"

The certificate state is failed. Make sure both records are still published and the CNAME points at points_to, then choose Check now to request it again.