Restricting API Access with API Keys

You can use API keys to restrict access to specific API methods or all methods in an API. This page describes how to restrict API access to those clients that have an API key and also shows how to create an API key.

If you set an API key requirement in your API, requests to the protected method, class, or API are rejected unless they have a key generated in your project or within other projects belonging to developers with whom you have granted access to enable your API. For more information, see Sharing APIs protected by API key.

Restricting access to all API methods

To require an API key for accessing all methods of an API follow the instructions in the tab for your language:

Python

To require an API key for all calls into the API, add api_key_required=True to your API decorator; for example:

 @endpoints.api(name='echo', version='v1', api_key_required=True)
 class EchoApi(remote.Service):
 #...

Java

To require an API key for all calls into the API, add apiKeyRequired = AnnotationBoolean.TRUE to your @Api annotation; for example:

 @Api(
     name = "echo",
     version = "v1",
     apiKeyRequired = AnnotationBoolean.TRUE
     )
 public class Echo {
 //API class and methods...
 }

Restricting access to specific API methods

To require an API key for accessing a specific methods in an API follow the instructions in the tab for your language:

Python

To require an API key for all calls to a specific API method, add api_key_required=True to your API method decorator; for example:

 endpoints.method(
    # This method takes an Echo message.
    ECHO_RESOURCE,
    # This method returns an Echo message.
    EchoResponse,
    path='echo',
    http_method='POST',
    name='echo_api_key',
    api_key_required=True)
 def echo_api_key(self, request):
     output_content = '\n'.join([request.content] * request.n)
     return EchoResponse(content=output_content)

Java

To require an API key for all calls into a specific API method, add apiKeyRequired = AnnotationBoolean.TRUE to your @ApiMethod annotation; for example:

@ApiMethod(name = "echo_api_key", path = "echo_api_key", apiKeyRequired = AnnotationBoolean.TRUE)
public Message echoApiKey(Message message, @Named("n") @Nullable Integer n) {
  return doEcho(message, n);
}

To require an API key for all calls into a specific API class, add apiKeyRequired = AnnotationBoolean.TRUE to your @ApiClass annotation.

Removing API key restriction for a method

To turn off API key validation for an API or API method, remove api_key_required=True (Python) or apiKeyRequired = AnnotationBoolean.TRUE (Java) from your API or method decorator or annotation. Then recompile and re-deploy.

Calling an API using an API Key

If an API or API method requires an API key, supply the key using a query parameter named key, as shown in this cURL example:

curl \
    -H "Content-Type: application/json" \
    -X POST \
    -d '{"message": "echo"}' \
    "${HOST}/_ah/api/echo/v1/echo_api_key?key=${API_KEY}

where HOST and API_KEY are variables containing your API host name and API key, respectively. Replace echo with the name of your API, and v1 with the version of your API.

Sharing APIs protected by API key

API keys are associated with the Google Cloud Platform (GCP) project in which they have been created. If you have decided to require an API key for your API, the GCP project that the API key gets created in depends on the answers to the following questions:

  • Do you need to distinguish between the callers of your API so that you can use Cloud Endpoints features such as quotas?
  • Are all your customers GCP customers?
  • Do you need to set up different API key restrictions?

You can use the following decision tree as a guide for deciding which GCP project the API key should be created in. After you have made a decision, see the sections below for more details.

API key decision tree

Grant GCP customers permission to enable the API

When you need to distinguish between callers of your API, and all your customers are GCP customers, you can grant them the permission to enable the API in their own GCP project. This way, your customers can create their own API key for use with your API.

To let customers create their own API key:

  1. In the GCP project in which your API is configured, grant each user the permission to enable your API.
  2. Contact the users, and let them know that they can enable your API in their own GCP project and create an API key.

Create a separate GCP project for each customer

When you need to distinguish between callers of your API, and not all of your customers are GCP customers, you can create a separate GCP project and API key for each customer. Before creating the projects, give some thought to the project names so that you can easily identify the customer associated with the project.

To create a separate GCP project and API key for each customer:

  1. Create a separate project for each customer.
  2. In each project, enable your API and create an API key.
  3. Give the API key to each customer.

Create an API key for each customer

When you do not need to distinguish between callers of your API, but you want to add API key restrictions, you can create a separate API key for each customer in the same project.

To create an API key for each customer in the same project:

  1. In either the project that your API is configured in, or a project that your API is enabled in, create an API key for each customer that has the API key restrictions that you need.
  2. Give the API key to each customer.

Create one API key for all customers

When you do not need to distinguish between callers of your API, and you do not need to add API restrictions, but you still want to require an API key (to prevent anonymous access, for example), you can create one API key for all your customers to use.

To create one API key for all customers:
  1. In either the project that your API is configured in, or a project that your API is enabled in, create an API key for all customers.
  2. Give the same API key to every customer.

Further reading

Send feedback about...

Cloud Endpoints Frameworks for App Engine