Stay organized with collections Save and categorize content based on your preferences.
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.
The Extensible Service Proxy (ESP) uses Service Control API to validate an API key and its association with a project's enabled API. 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. The project that the API key was created in isn't logged and isn't added to the request header. You can, however, view the Google Cloud project that a client is associated with in Endpoints > Services, as described in Filter for a specific consumer project.
For information on which Google Cloud project an API key should be created in, see Sharing APIs protected by API key.
Restricting access to all API methodsTo require an API key for accessing all methods of an API:
Open your project's openapi.yaml file in a text editor.
Under securityDefinitions:, add api_key: values apiKey, key, query as shown in the sample code snippet:
This establishes a "security scheme" called api_key, which you can use to protect the API. For other api_key definition options, refer to Api key definition limitations.
At the top level of the file (not indented or nested), add api_key: [] to the security directive . You may need to add the security directive or it may already be present:
security:
- api_key: []
This directive applies the api_key security scheme to all methods in the file. Don't place anything inside the brackets. The OpenAPI specification requires an empty list for security schemes that don't use OAuth.
To require an API key for a specific method:
Open your project's openapi.yaml file in a text editor.
At the top level of the file (not indented or nested), add an empty security directive to apply it to the entire API:
security: []
Under securityDefinitions:, add api_key: values apiKey, key, query as shown in the sample code snippet:
This establishes a "security scheme" called api_key, which you can use to protect the API. For other api_key definition options, refer to Api key definition limitations.
Add api_key: [] to the security directive in the method's definition:
...
paths:
"/echo":
post:
description: "Echo back a given message."
operationId: "echo"
security:
- api_key: []
produces:
...
This directive applies the api_key security scheme to the method. Don't place anything inside the brackets. The OpenAPI specification requires an empty list for security schemes which don't use OAuth.
To turn off API key validation for a particular method even when you've restricted API access for the API:
Open your project's openapi.yaml file in a text editor.
Add an empty security directive in the method's definition:
...
paths:
"/echo":
post:
description: "Echo back a given message."
operationId: "echo"
security: []
produces:
...
If an API or API method requires an API key, supply the key using a query parameter named key, as shown in the following curl example:
curl "${ENDPOINTS_HOST}/echo?key=${ENDPOINTS_KEY}"
where ENDPOINTS_HOST and ENDPOINTS_KEY are environment variables containing your API hostname and API key, respectively.
API keys are associated with the Google Cloud project in which they have been created. If you have decided to require an API key for your API, the Google Cloud project that the API key gets created in depends on the answers to the following questions:
You can use the following decision tree as a guide for deciding which Google Cloud project to create the API key in.
Grant permission to enable the APIWhen you need to distinguish between callers of your API, and each caller has their own Google Cloud project, you can grant principals permission to enable the API in their own Google Cloud project. This way, users of your API can create their own API key for use with your API.
For example, suppose your team has created an API for internal use by various client programs in your company, and each client program has their own Google Cloud project. To distinguish between callers of your API, the API key for each caller must be created in a different Google Cloud project. You can grant your coworkers permission to enable the API in the Google Cloud project that the client program is associated with.
To let users create their own API key:
When you need to distinguish between callers of your API, and not all of the callers have Google Cloud projects, you can create a separate Google Cloud project and API key for each caller. Before creating the projects, give some thought to the project names so that you can easily identify the caller associated with the project.
For example, suppose you have external customers of your API, and you have no idea how the client programs that call your API were created. Perhaps some of the clients use Google Cloud services and have a Google Cloud project, and perhaps some don't. To distinguish between the callers, you must create a separate Google Cloud project and API key for each caller.
To create a separate Google Cloud project and API key for each caller:
When you don't 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 caller in the same project.
To create an API key for each caller in the same project:
When you don't need to distinguish between callers of your API, and you don't 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 callers to use.
To create one API key for all callers:
If you rely on API keys to protect access to your API and user data, make sure that you set the --service_control_network_fail_policy flag to close when configuring the Extensible Service Proxy V2 (ESPv2) startup options. The default value for the flag is open.
ESPv2 calls Service Control to verify API keys. If there are network failures when connecting to Service Control and ESPv2 cannot verify the API key, this results in any potential requests made to your API with fraudulent keys being rejected.
What's nextExcept as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-08-07 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-07 UTC."],[[["API keys can restrict access to specific API methods or an entire API, ensuring only authorized clients can make requests."],["The Extensible Service Proxy (ESP) validates API keys using the Service Control API, rejecting requests without a valid key."],["To require an API key for all API methods, add the `api_key` security scheme in the `securityDefinitions` and apply it in the `security` directive at the top level of the `openapi.yaml` file."],["To restrict access to a specific API method, define the `api_key` security scheme in `securityDefinitions` and apply it within the `security` directive of that method's definition in the `openapi.yaml` file."],["Deciding where to create API keys depends on whether you need to distinguish callers, if all callers have Google Cloud projects, or if you need to add specific API key restrictions."]]],[]]
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4