Setting up a custom domain

As of March 21, 2022, Cloud Endpoints Portal is deprecated. Cloud Endpoints Portal will no longer be available after March 21, 2023. API traffic managed by Cloud Endpoints is not affected by this change. For more information, see Feature deprecations.

When you create a portal for your Cloud Endpoints API, by default the portal is hosted on the cloud.googdomain, which Google owns and manages. The default URL to your portal is in the following format where YOUR_PROJECT_ID is the Google Cloud project that you deployed your Endpoints configuration to:

https://endpointsportal.YOUR_PROJECT_ID.cloud.goog

If you want the users of your API to access your portal using a custom domain, you need to configure the Cloud Endpoints Portal and the DNS settings in your domain name registrar. When you add a custom domain to your portal, the Endpoints Portal displays the type of DNS record and other information that you need to configure in your domain name registrar.

This page describes how to configure the Endpoints Portal to use a custom domain. For each task, the minimum required Identity and Access Management role (or roles) required to complete the task is provided. For more information about IAM permissions, see the following:

• Understanding roles
• Granting, changing, and revoking access to resources
• Creating and managing custom roles

Prerequisites

This guide assumes that:

• You have created your portal.
• You are a verified owner of the domain you want to use. Additionally, you need to know how to configure DNS in your domain name registrar.

Adding a custom domain

Permissions required for this task

To perform this task, you must have endpoints.portals.listCustomDomains and endpoints.portals.attachCustomDomain on the project. The Project Viewer role plus the Endpoints Portal Admin on the project have the required permissions. The Project Editor role on the project also has the required permissions.

1. In the Google Cloud console, go to the Endpoints > Developer Portal page for your project.

   Go to the Cloud Endpoints Portal

2. Click Add a custom domain.
3. Enter either a root domain or subdomain name.
4. To add the domain, click Continue.

5. The Endpoints Portal displays Update your DNS records. Add the DNS records using your domain name registrar for all the records listed in the Update your DNS records section.

   • If you entered a root domain such as example.com, the Update your DNS records section displays a list of A records and AAAA records with IP addresses. For example:

     Type	Data	Alias
     A	198.51.100.0	-
     A	198.51.100.2	-
     A	198.51.100.4	-
     A	198.51.100.6	-
     AAAA	2001:db8:ffff:32::15	-
     AAAA	2001:db8:ffff:34::15	-
     AAAA	2001:db8:ffff:36::15	-
     AAAA	2001:db8:ffff:38::15	-

     The configuration steps and terminology for adding multiple A and AAAA records for a domain name vary depending on your domain name registrar. If you are unsure, search the documentation for your domain name registrar for terms such as record set or multiple responses.

   • If you entered a subdomain such as apidocs.example.com, the Update your DNS records section displays a CNAME. For example:

     Type	Data	Alias
     CNAME	ghs.googlehosted.com	apidocs

6. Click Done.

7. To visit your portal, click the custom domain link. It might take up to 24 hours for a functional custom domain link depending on DNS record propagation.

Google provisions an SSL certificate only after you add the DNS records using your domain registrar. Until then, the custom domain doesn't work with your portal, even using http://. However, you can continue using the default URL that is displayed on the Endpoints > Developer Portal page.

Viewing the information to add to DNS

Permissions required for this task

To perform this task, you must have endpoints.portals.listCustomDomains on the project. The Project Viewer role plus the Endpoints Portal Admin on the project have the required permission. The Project Editor role on the project also has the required permission.

To see the information that you need to add (or that is already added) to your domain name registrar:

1. In the Google Cloud console, go to the Endpoints > Developer Portal page.

   Go to the Cloud Endpoints Portal

2. Select the Google Cloud project that owns the API.
3. Next to your custom domain, click DNS details.

Deleting a custom domain

Permissions required for this task

To perform this task, you must have endpoints.portals.listCustomDomains and endpoints.portals.detachCustomDomain on the project. The Project Viewer role plus the Endpoints Portal Admin on the project have the required permissions. The Project Editor role on the project also has the required permissions.

1. In the Google Cloud console, go to the Endpoints > Developer Portal page for your project.

   Go to the Cloud Endpoints Portal

2. Next to DNS details for your custom domain, click Delete .
3. In the confirmation dialog, click Delete.

Troubleshooting

Adding a custom domain fails with a generic error. There might be many reasons for this. Make sure that the default URL to your portal, endpointsportal.YOUR_PROJECT_ID.cloud.goog, is functional. If the default URL doesn't work, delete the portal and then follow the steps in Creating a portal for your Endpoints API to recreate it.

Adding a custom domain failed, but it still shows up in the main page's table. This is a known issue. To resolve the issue, delete the custom domain, and then add it again.

Clicking the "DNS details" shows an empty table with no records to add. This can happen if adding the custom domain failed, but it still shows up in the table. To resolve the issue, delete the custom domain, and then add it again.

The custom domain link doesn't work. You need to ensure that you've added the DNS records correctly with your domain registrar. It can take up to 24 hours for the custom domain to work.

I don't have permission to add a custom domain. Minimally, you must have the Project Viewer role plus the Endpoints Portal Admin on the project. The Project Editor role on the project also has the required permissions. See Creating and managing custom roles for more information.

I would like to reuse the same domain name I have used for my App Engine application. A specific domain name can only serve one web application. You can't use the same domain name for your App Engine web application and for your portal. Use a unique domain name.

What's next

Learn about:

• The permissions in the Endpoints Portal Admin role
• Trying out the API in your portal