Controlling Who Can Enable Your API

If an API requires an API key or any sort of authentication, then users of your API must enable it in their own Cloud projects before they can call it. This page shows you how to control who can enable your API. If you have been granted the right to enable an API, this page shows you how to enable it.

By default, a Google Cloud Endpoints service is private to the project that it was created in. Only the Cloud project members can see it in the APIs list on the Endpoints dashboard. Additionally, only keys from that same project can be used for those API methods that require a key. When you grant someone who is not a project member access to your API, they can enable your service in their own project and generate an API key, if one is needed.

Granting Access

Cloud Endpoints uses the Google Cloud Identity and Access Management (IAM) Service Consumer role to allow someone who is not a member of your Cloud project to enable your API in their own Cloud project. (In previous versions of Cloud Endpoints, the "Share an API" feature did not use IAM.) You can grant access using the Cloud Platform Console or the command line.

Console

1. In the Cloud Platform Console, go to the Endpoints dashboard for your project.

   Endpoints Dashboard

2. Click the name of the API you want to grant access to.
3. If the Permissions side panel is not open, click +Permissions.
4. In the Add members field, enter the email address of the person you want to grant access to, or enter the name of the Google Group that contain the members you want to grant access to.
5. In the Select a role drop-down, select Service Consumer, which maps to the IAM role roles/servicemanagement.serviceConsumer.
6. Repeat adding members and selecting the role, as needed.
7. Click Add to add the member(s) to the IAM role.
8. Contact the users or groups that you added and let them know they can enable the API in their projects. See Enable an API in Your Cloud Project for information on how to enable a service in APIs & services.

Command Line

1. Open Cloud Shell, or if you have the Cloud SDK installed, open a terminal window.
   • If you are granting access to an individual user, invoke the following:

     gcloud service-management add-iam-policy-binding [SERVICE-NAME] \ --member='user:[EMAIL-ADDRESS]' \ --role='roles/servicemanagement.serviceConsumer'

     For example:

     gcloud service-management add-iam-policy-binding example-service-name \ --member='user:[e-mail]' \ --role='roles/servicemanagement.serviceConsumer'

   • If you are granting access to a Google Group, invoke the following:

     gcloud service-management add-iam-policy-binding [SERVICE-NAME] \ --member='group:[GROUP-NAME]@googlegroups.com' \ --role='roles/servicemanagement.serviceConsumer'

     For example:

     gcloud service-management add-iam-policy-binding example-service-name \ --member='group:[e-mail]' \ --role='roles/servicemanagement.serviceConsumer'

2. Contact the users or groups that you added and let them know they can enable the API in their projects. See Enable an API in Your Cloud Project for information on how to enable a service in APIs & services.

Revoking Access

You revoke access to your API by removing the IAM Service Consumer role from a user or group that previously had the role. After you revoke someone's access, they will no longer be able to find and enable your API.

Important: If someone has already activated your API, revoking access will not prevent them from calling your API. Although there is no easy way to to prevent these calls post-activation, you could restrict access by API key and then add logic that disallows calls from that consumer's API key.

You can revoke access using the console or the command line.

Console

1. In the Cloud Platform Console, go to the Endpoints dashboard for your project.

   Endpoints Dashboard

2. Click the name of the API you want to revoke access to.
3. If the Permissions side panel is not open, click +Permissions.
4. Click on the Role card that the member belongs to. Alternatively, you can search for the member by using Search members field
5. Hover over the member and click the trash can to remove the member from the role.

Command Line

• If you are revoking access for an individual user, invoke the following:

  gcloud service-management remove-iam-policy-binding [SERVICE-NAME] \ --member='user:[EMAIL-ADDRESS]' --role='[ROLE-NAME]'

  For example:

  gcloud service-management remove-iam-policy-binding example-service-name \ --member='user:[e-mail]' \ --role='roles/servicemanagement.serviceConsumer'

• If you are revoking access for a Google Group, invoke the following:

  gcloud service-management remove-iam-policy-binding [SERVICE-NAME] \ --member='group:[GROUP-NAME]@googlegroups.com' \ --role='[ROLE-NAME]'

  For example:

  gcloud service-management remove-iam-policy-binding example-service-name \ --member='group:[e-mail]' \ --role='roles/servicemanagement.serviceConsumer'

Enable an API in Your Cloud Project

To use an API that you have been granted access to:

1. In the Cloud Platform Console, go to APIs & services for your project.

   APIs & services

2. On the Library page, click Private APIs.
3. Click the API you want to enable. If you need help finding the API, use the search field. A page displays with information about the API.
4. Click Enable.

If the API has methods that require an API key, you'll be prompted to generate credentials (an API key); follow the prompts to create the API key. You are now ready to call the API, supplying the API key to those methods that require a key.