API Portal
Custom domain
Point your own domain at your API Portal. Add the domain in the dashboard, create the CNAME records Apiable generates at your DNS provider, and let Apiable provision the SSL certificates through AWS Certificate Manager. Covers the UNDEFINED, PENDING_VALIDATION, ISSUED, and FAILED states.
You can serve your API Portal from your own domain, such as developers.yourcompany.com, instead of the default your-tenant.apiable.io address. You add the domain in the dashboard, Apiable generates CNAME records and requests SSL certificates, and you add those records at your DNS provider so the certificates validate.
How do you point a custom domain at your portal?
Open Settings in the dashboard, go to the custom domain section, enter your domain, and choose Add domain. Apiable validates the domain, requests the SSL certificates, and then shows the CNAME records you add at your DNS provider.
- Open Settings in the dashboard and go to the custom domain section.
- Enter your domain, for example
developers.yourcompany.com. - Choose Add domain. The button enables only once the domain has a valid top-level domain.
- Apiable starts provisioning. The DNS records section appears with the CNAME records to create.
- Add each CNAME record at your DNS provider.
- Wait for the certificates to be issued. The portal then switches to your domain.
While the domain is provisioning, the section refreshes on its own every couple of seconds, and any record still being generated shows "Automatically generating ...". You do not need to reload the page.
What DNS records do you create?
Apiable generates the CNAME records for you. The DNS records section lists each record's name and value, each with a copy button. You create those CNAME records at your DNS provider so AWS Certificate Manager can validate the domain.
| Record | What it is for |
|---|---|
| Your domain to origin | Maps your custom domain to your portal's origin address, in the form your-tenant.apiable.io. |
| Certificate validation CNAME | The name and value AWS Certificate Manager needs to validate the certificate for your domain. |
How does Apiable provision the SSL certificate?
Apiable provisions SSL through AWS Certificate Manager using DNS validation. It requests one certificate for the portal frontend and one for the backend, waits for the validation records, then polls each certificate until it is issued. When both are issued, Apiable switches your portal to the custom domain.
- On save, Apiable requests two certificates: a frontend certificate and a backend certificate. Each also covers
*.apiable.io. - Apiable waits for each certificate's DNS validation record, then writes the configuration to pending validation with the CNAME records for you to add.
- You add the CNAME records. ACM validates the domain once they resolve.
- Apiable polls each certificate until it reaches issued, for up to 24 hours.
- When both certificates are issued, the status becomes issued and Apiable updates the content delivery and load-balancer configuration to serve your domain.
If either certificate fails to issue, Apiable deletes that unissued certificate and sets the status to failed.
What do the custom domain states mean?
The custom domain moves through a small set of states as the certificates are provisioned. The status reflects where the certificates are in that process.
| State | What it means |
|---|---|
| Undefined | No domain is being provisioned yet, or provisioning has not started. A new domain can be added only in this state. |
| Pending validation | Certificates have been requested and the CNAME records are shown. ACM is waiting for the records to resolve at your DNS provider. |
| Issued | Both certificates were issued. Apiable has switched the portal's delivery and load balancer to your domain. |
| Failed | A certificate could not be issued. The unissued certificate is removed. Review the records and contact Apiable to retry. |
| Invalid | The domain did not pass validation. Correct the domain and add it again. |
Can you change a custom domain later?
A new domain can be added only while the status is undefined. Once a domain is being provisioned, the input field locks, and the backend rejects a second change with the error "Could not update the Custom Domain configuration ... twice." To change a domain that is already in progress or live, contact Apiable.
This guard is deliberate. Switching a live domain means re-issuing certificates and re-pointing delivery, so it is handled with Apiable rather than as a self-service edit.
Troubleshooting
Match the state or message to the fix.
| What you see | What to do |
|---|---|
| Add domain stays disabled after typing a domain | The button enables only for a valid top-level domain, and the section must be in the undefined state. Check the domain spelling and that no domain is already provisioning. |
| The whole section shows an entitlement notice | Custom domains are not included in your plan. Contact Apiable to enable the feature. |
| The input is locked and you cannot edit the domain | A domain is already being provisioned or is live. The field unlocks only in the undefined state. Contact Apiable to change it. |
| Status sits on pending validation | ACM is waiting for your CNAME records. Confirm the exact name and value were added at your DNS provider and allow time for DNS to propagate. |
| A record shows "Automatically generating ..." | Apiable is still generating that record. The section refreshes on its own every couple of seconds. Leave it open. |
| Status shows failed | A certificate could not be issued and was removed. Re-check the validation records at your DNS provider, then contact Apiable to retry provisioning. |
| Error "unable to update while subdomain updating" | Your portal's base subdomain is mid-update. Wait for that to finish, then add the custom domain. |
Where to next
Portal details and registration
Set the portal name, the sign-up approval flow, and the registration form.
Portal security and MFA
Password-protect the portal and configure multi-factor authentication.
API Portal overview
How the portal pages, theme, and navigation fit together.
Partner and developer onboarding
What signing in and the first API call look like from the developer's side.