API Portal
Custom domain
Serve your API Portal on your own domain: add the domain under Settings, Portal settings, Domains, create the two CNAME records the page shows, and let Apiable issue the certificates and switch your portal over. Covers what the page shows while that happens and how to fix common problems.
You can serve your API Portal from your own domain, such as developers.yourcompany.com, instead of its your-tenant.apiable.io address. You add the domain in the dashboard, create the two CNAME records it shows, and Apiable issues the certificates and moves your portal over.
How do you point a custom domain at your portal?
Open Settings, Portal settings, Domains, enter your domain and choose Add domain. Two CNAME records then appear under DNS Settings. Create both at your DNS provider, and Apiable completes the rest.
- Open Settings at the bottom of the dashboard sidebar, then Portal settings, then Domains.
- Under Custom domain, enter your domain, for example
developers.yourcompany.com. - Choose Add domain. It enables once the domain ends in a recognised top-level domain.
- Wait for DNS Settings to fill in. Domain Validation shows "Automatically generating ..." until its record is ready, and the page refreshes on its own until then.
- Create both records at your DNS provider, as described below.
- Wait for Apiable to finish. Adding the domain notifies Apiable's team, who complete the switch-over once the certificates are issued.
The page adds a note that it can take up to 24 hours for your new domain to come into full effect. If your portal does not answer on the domain after 48 hours, contact Apiable.
What DNS records do you create?
Two CNAME records, both shown under DNS Settings with a Name, a Value and copy buttons. One points your domain at your portal. The other lets AWS Certificate Manager confirm that you own the domain.
| Record | Name | Value |
|---|---|---|
| Custom Domain Mapping | Your domain, for example developers.yourcompany.com. | Your portal's current address, shown as https://your-tenant.apiable.io. Enter it without https://, as your-tenant.apiable.io. |
| Domain Validation | The name AWS Certificate Manager generated. | The value AWS Certificate Manager generated. Enter both exactly as shown. |
How does Apiable issue the certificates?
Through AWS Certificate Manager, with DNS validation. Apiable requests two certificates for your domain, one for the portal site and one for its API, and checks for up to 24 hours until both are issued.
- When you choose Add domain, Apiable requests the certificates and creates the validation record. This usually takes a few minutes.
- You add both CNAME records.
- AWS Certificate Manager validates the domain once the records resolve.
- When both certificates are issued, Apiable points your portal's delivery at your domain and completes the switch-over.
If a certificate is not issued within 24 hours, Apiable removes it. Check your records, then contact Apiable to try again.
What does the Domains page show while this happens?
The records, not a status. The page has no indicator for validation or issuing, so use this table to read it, and check your domain in a browser to see whether it is live.
| What you see | What it means |
|---|---|
| DNS Settings does not appear | No domain has been added yet. |
| Domain Validation shows "Automatically generating ..." | The validation record is being created. The page refreshes on its own. |
| Both records filled in and the domain field locked | The records are ready. Add them at your DNS provider if you have not, then wait for the switch-over. |
What changes as soon as you add a domain?
Links in the emails your portal sends, such as invitations and notifications, start using your custom domain straight away, before it is live. Add the DNS records promptly so those links work.
Can you change a custom domain later?
Not from the dashboard. Once the records are generated, the domain field stays locked. To change or remove a domain that is being set up or is live, contact Apiable.
Troubleshooting
Match what you see to the fix.
| What you see | What to do |
|---|---|
| Add domain stays disabled | Check the spelling. The domain must end in a recognised top-level domain, and no other domain can already be set up. |
| "Invalid domain format!" | Enter only the hostname, for example developers.yourcompany.com, without https:// or a path. |
| "Could not update the custom domain while updating subdomain of the portal." | Your portal's own address is being updated. Wait for that to finish, then add the domain. |
| "Please upgrade to access this feature" | Your plan does not include custom domains. Talk to sales. |
| The domain field is locked | A domain is already set up or in progress. Contact Apiable to change it. |
| "Automatically generating ..." is still there after 20 minutes | The validation record was not created. Contact Apiable. |
| Your DNS provider rejects the Custom Domain Mapping value | Remove https:// from the value. |
| The portal does not answer on your domain after 48 hours | Confirm both records resolve, then contact Apiable. |
Where to next
Portal details and registration
Set the portal name, sign-up approval, and the registration form.
Portal security and MFA
Restrict access to the portal and set multi-factor authentication.
Theme
Point the email footer at your new domain with Footer domain.
API Portal overview
How the portal pages, theme, and navigation fit together.