Setting up a custom domain

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
This is the default URL even if you specified a custom domain (such as example.com or my-api.example.com) in the hostfield of your OpenAPI document.

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 Cloud Identity and Access Management role (or roles) required to complete the task is provided. For more information about Cloud IAM permissions, see the following:

Prerequisites

This guide assumes that:

Adding a custom domain

  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

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

  1. In the 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

  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 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:

Was this page helpful? Let us know how we did:

Send feedback about...

Cloud Endpoints with OpenAPI
Need help? Visit our support page.