Each project has an API address chosen for it. With a custom domain, an environment also answers on a hostname of yours, such as api.yourapp.com for production and staging-api.yourapp.com for staging. Your apps, links in emails and webhook callers then use your brand’s address.

​
How it works

  1. You add a hostname to an environment.
  2. Pawabase gives you a DNS TXT record to prove you own it.
  3. You add the record at your DNS provider and verify.
  4. You point the hostname at your API with a CNAME (or A) record.
  5. Requests to that hostname are served by that environment.
A hostname serves one environment.

​
Add a domain

Custom domains are managed with the management API, using a secret key (Studio’s Users & auth → Domains page is a different thing: the addresses a browser may be sent back to after signing in). Add the hostname, for example api.yourapp.com, as shown in From code below. The hostname must be a real hostname (at least two parts, like api.example.com), not an IP address, at most 253 characters. A hostname already registered is refused. The answer includes the record to add (record):

​
Verify it

Add the TXT record at your DNS provider, wait a few minutes for it to spread, then call verify. Pawabase looks the record up and the domain becomes: Once verified, a domain stays verified even if a later check can’t find the record, so removing the TXT record afterwards doesn’t take your API down. You can keep it, though, as a record of ownership.

​
Point it at your API

After verification, add a CNAME record for the hostname that points at your project’s API address (shown in Studio’s Overview), or an A record if your DNS provider can’t use a CNAME at that name.

​
HTTPS

Pawabase checks ownership and routes the hostname to the environment. Visitors need an HTTPS certificate for the hostname, which is provided by whatever terminates TLS in front of your API. If you put your own proxy or CDN in front (Cloudflare, a load balancer), set its certificate for the hostname there.

​
What changes for keys

An API key belongs to one environment. When a request arrives on a custom domain, it must use a key of that domain’s environment: a staging key used on api.yourapp.com (production) is refused with host_environment_mismatch. This stops a test key from being used against production by mistake.

​
From code

Adding, checking and removing domains is recorded in the audit log.

​
After switching

  • Update your apps’ API URL to the new hostname.
  • Add the new address to redirect URLs and to Websites allowed to call it in Environment settings where needed.
  • Tell partners whose systems call your inbound hooks about the new address, or keep the old one working too.

​
Troubleshooting