Custom domains for your mock API

By default a mock answers under the Mockfly domain and the namespace of its project: https://api.mockfly.dev/mocks/{namespace}/users. With a custom domain the same mock answers at https://api-mock.yourcompany.com/users: your hostname, no /mocks/{namespace} prefix, and a TLS certificate issued and renewed for you.

That changes how you plug Mockfly into an app:

Swap the backend with a DNS change. Point api-mock.yourcompany.com at Mockfly while the real API is being built, then point it at the real API when it ships. Nothing in the app changes.
Keep the paths absolute. SDKs, generated clients and mobile builds that hardcode paths like /v1/users work as they are, because there is no prefix to add.
A URL that looks like the real thing for staging, QA and demos, instead of a namespace nobody remembers.

Custom domains are part of the Pro and Team plans. The classic api.mockfly.dev/mocks/{namespace} URL keeps working next to the custom one.

Requirements

The admin of the project is on Pro or Team. Every member of the project then gets the domain, free accounts included.
A domain you control, with access to its DNS. Use a subdomain such as api-mock.yourcompany.com. A bare domain like yourcompany.com only works if your DNS provider supports CNAME flattening or ALIAS records, because a CNAME cannot live at the apex.
One custom domain per project. A hostname can be attached to a single Mockfly project, and subdomains of mockfly.dev are not allowed.

Add the domain

Open the project settings (the gear icon on the project card, or the sidebar inside the project) and go to Custom domain, right below the proxy configuration. Type the hostname without protocol, path or port (api-mock.yourcompany.com, not https://api-mock.yourcompany.com/) and click Add.

Mockfly registers the hostname and shows the DNS record you have to create. The domain starts in the pending state and stays there until the DNS points at Mockfly.

Create the CNAME record

In the DNS panel of your provider, add a CNAME record for the hostname pointing at edge.mockfly.dev:

Type	Name	Value
CNAME	api-mock	edge.mockfly.dev

Some providers want the full name (api-mock.yourcompany.com) and others only the part before your domain (api-mock). The app shows both.
If your domain is itself on Cloudflare, create the record as DNS only (grey cloud, proxy off) so the certificate validation reaches Mockfly.
Do not keep an A or AAAA record on the same name: a CNAME has to be the only record for the hostname.

Verify the domain

Back in Mockfly, click Verify. Mockfly checks that the CNAME points at edge.mockfly.dev and that the TLS certificate for your hostname has been issued. DNS changes usually show up within minutes, and the certificate follows a few minutes after the CNAME is visible. While the domain is pending the app keeps checking on its own; you can also click Verify whenever you want.

When both checks pass, the domain becomes active and your mocks answer on it. If something is wrong with the DNS or the certificate, the domain moves to error with the reason next to it.

Use the domain

# the classic URL keeps working
curl https://api.mockfly.dev/mocks/{namespace}/users/42

# the same mock on your domain, no prefix
curl https://api-mock.yourcompany.com/users/42

# WebSocket endpoints too
wscat -c wss://api-mock.yourcompany.com/ws

Everything configured on the project applies on the custom domain: conditional rules, Faker.js placeholders, body substitution, custom headers, delays, proxy mode, request logs and WebSocket endpoints. On your domain every path is a mock: there is no Mockfly API or dashboard under it, so /users there is always the /users endpoint of your project.

To point an app at the mock, set its API base URL to https://api-mock.yourcompany.com. To move that app to the real backend later, change where the CNAME points and leave the app alone.

Statuses

Status	Meaning	What to do
`pending`	Waiting for the CNAME or for the certificate.	Create the CNAME and click Verify.
`active`	The domain serves your mocks over HTTPS.	Nothing.
`moved`	The CNAME no longer points at edge.mockfly.dev. The project admin gets an email.	Point the CNAME back and click Verify.
`suspended`	The subscription of the project admin ended. The domain stops serving; the classic URL keeps working.	Subscribe again and click Verify.
`error`	The certificate could not be issued, or the hostname was rejected. The reason is shown next to it.	Fix the DNS and click Verify, or write to [email protected].

Good to know

A domain that is never verified is removed automatically after seven days, so nobody can hold a hostname they do not control.
Removing the domain from the project, or deleting the project, deletes its certificate. The classic URL is not affected.
Changing the namespace of the project does not touch the custom domain, and the other way around.
Requests through the custom domain count for the project exactly like the ones through the classic URL, and show up in the same logs.

Create a project