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 in project of a developer who shares your API.

For more information about API keys, see Why and When to Use API keys

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

You can share your API with other developers so they can enable the API on their own cloud project and generate their own API key for use in calling your API. For more information, see Sharing an API.

Creating an API key

If you use API key protection for your API, clients need to provide a valid API key when calling the API. You can provide clients with a valid API key generated within your project, or optionally, if you share your API with developers, those developers can also generate a valid API key.

  1. Create a server API key.

    Go to the Create server API key page.

  2. Give the key to developers who want to call your API.

Further reading

For background information about Api keys and how they differ from user authentication, see When and Why to use Api Keys.

Monitor your resources on the go

Get the Google Cloud Console app to help you manage your projects.

Send feedback about...

Cloud Endpoints Frameworks for App Engine