Note that this feature is only available on the Plus plans and above.
Note also that the procedure involves several approval steps – so please allow plenty of time (we recommend 2 weeks) to initiate the change before it is required.
This is part of a 3 part series on branding. See the other sections:
At the end of this how to you will have changed the URL of your portal to a new location under your own company domain name so that you can publicize it under your own brand.
Step by Step
Step 1: Add a CNAME entry to your DNS Setup
Configure your own DNS records to point to the location of 3scale’s servers.
CNAME developer.mydomain.com pointing to mydomain.3scale.net
Note developer.mydomain.com is the most popular domain among 3scale customers. You need to implement the CNAME via your DNS provider, for examples with GoDaddy and eNom see below.
Normally you will want to make the change to your custom domain before you allow public access to your developer portal. In case you already have public users, you should bear in mind that it is not possible to define a redirect from mydomain.3scale.net to your custom domain. Therefore you would need to inform your users about the domain change.
It is best to implement the CNAME in advance. In a few rare cases this is not possible such as when you have an existing site in public use at that domain. If this applies please contact 3scale support to determine the best way to synchronize a switchover
Step 2: Request the domain change and SSL Certificate from 3scale
All API portals run under SSL and hence when switching to your own domain you will need to enable an SSL Certificate for your domain. Inform 3scale with the following information:
- Your company name.
- The domain name you would like to activate (which needs to be a domain within your control) e.g. developer.yourdomain.com
3scale will confirm the domain name procedure and initiate the creation of an SSL certificate using Digicert. As part of the process an email will be sent from the certificate provider (DigiCert) to the registered contact owner of your domain. This is often a named person in your organisation or a generic address such as firstname.lastname@example.org*.
The email will request approval of the creation of an SSL certificate for the subdomain and the person in question will need to approve creation.
It is important before initiating the process to inform the individual who will receive the above email that this is happening.
Once the certificate is issued it will be issued to cover the portal and 3scale will confirm once this has been done.
Step 3: Approve the SSL certificate to be issued
Within a maximum of one week after receiving the SSL certificate approval, 3scale will complete the domain switch in our systems and will inform you.
Step 4: Wait for the DNS configuration to propagate
The DNS records need to propagate before users start to be able to associate the new location with this address. This normally takes about 30 mins, but can take up to 24hrs. If it takes longer than this, check that the record has been correctly associated with the domain. You can do this by using a tools such as nslookup or dig on the subdomain.
Step 5: Final clean up
Review and test your portal carefully after the domain change. In particular:
- any ActiveDocs will require an update to reflect the new domain
- any links to the custom domain which are not relative must be updated
This section provides instructions for making the DNS change using various popular registrars.
- Log in to your account at http://www.godaddy.com by navigating to the My Account tab.
- Under the Domains section, find the domain you wish to use for the developer portal and click Advanced Details on the domain.
- In the DNS Manager section, click Launch.
- Select Quick Add In the CNAME section.
- In the new entry, enter the following information:
- Host: enter the name of the subdomain you plan to use for the CNAME, e.g. if you want to use “developer.mydomain.com” then enter “developer”.
- Points to: Enter yourdomain.3scale.net.
- TTL: Leave the TTL value at the default value.
At the top or the bottom of the page, click Save Zone File, followed by OK in the pop-up. Your CNAME should now be configured – bear in mind that it may take 24hrs for the records to propagate.
Log in to your account at www.enom.com.
- Log in to your account at http://www.enom.com.
- From the menu at the Domains tab, select My Domain to get to the Manage Domains page.
- Find and click the domain you wish to use for the developer portal and click Advanced Details on the domain.
- Click Host Settings.
- Click on NEW ROW and enter the name of the subdomain you plan to use for the CNAME, e.g. if you want to use “developer.mydomain.com” then enter “developer”.
- For the Host Name enter yourdomain.3scale.net.
- Click Save.
Your CNAME should now be configured – bear in mind that it may take 24hrs for the records to propagate.