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.

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

Restricting access to all API methods

If you set an API key requirement for the whole API, requests are rejected unless they have a key generated in your project or in project of a developer who shares your API.

To require an API key for accessing all methods of an API:

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

    securityDefinitions:
      # This section configures basic authentication with an API key.
      api_key:
        type: "apiKey"
        name: "key"
        in: "query"

    This establishes a "security scheme" called api_key which you can use to protect the API.

  2. Add api_key: [] to the security directive at the top level of the file (not indented or nested). You may need to add the security directive or it may already be present:

      security:
        - api_key: []
    

    This directive will apply the api_key security scheme to all methods in the file. Do not place anything inside the brackets. The OpenAPI specification requires an empty list for security schemes which do not use OAuth.

Restricting access to specific API methods

To require an API key for a specific method:

  1. Open your project's openapi.yaml file in a text editor.

  2. Add an empty security directive at the top level of the file (not indented or nested) to apply it to the entire API:

    security: []
    
  3. Under securityDefinitions:, add api_key: values apiKey, key, query as shown in the sample code snippet:

    securityDefinitions:
      # This section configures basic authentication with an API key.
      api_key:
        type: "apiKey"
        name: "key"
        in: "query"

    This establishes a "security scheme" called api_key which you can use to protect the API.

  4. 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 will apply the api_key security scheme to this method. Do not place anything inside the brackets. The OpenAPI specification requires an empty list for security schemes which do not use OAuth.

Removing API key restriction for a method

To turn off API key validation for a particular method even when you've restricted API access for the API:

  1. Open your project's openapi.yaml file in a text editor.

  2. Add an empty security directive in the method's definition:

    ...
    paths:
      "/echo":
    post:
      description: "Echo back a given message."
      operationId: "echo"
      security: []
      produces:
      ...
    

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 "${ENDPOINTS_HOST}/echo?key=${ENDPOINTS_KEY}"

where ENDPOINTS_HOST and ENDPOINTS_KEY are environment variables containing your API host name and API key, respectively.

Alternatively, you can pass the API key using the HTTP header 'x-api-key':

 curl "${ENDPOINTS_HOST}/echo" -H "x-api-key:${ENDPOINTS_KEY}"

In the above curls, ENDPOINTS_HOST and ENDPOINTS_KEY begin with a $ and are surrounded by curly braces because these are environment variables. If you do not use environment variables in the curl, do not include the $ or curly braces.

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.

Send feedback about...

Cloud Endpoints with OpenAPI