Using API Keys

This page describes how to use API keys in API Gateway.

An API key is a string that identifies a Google Cloud project for quota, billing, and monitoring purposes. Developers generate an API key in a project in the Google Cloud console. They then embed that key in every call to your API as a query parameter or in a request header.

If you specify an API key requirement in your API config, API Gateway uses the API key to look up the associated Google Cloud project. API Gateway rejects requests unless the API key was generated in your Google Cloud project or within other Google Cloud projects in which your API has been enabled.

Note: Unlike credentials that use short-lived tokens or signed requests, API keys are included as part of the API request. As a result, API keys are susceptible to man-in-the-middle attacks and are less secure than other authentication credentials. You can use API keys in addition to one of the other supported forms of authentication, but we don't recommend using only API keys when API calls contain sensitive data.

To create an API key, or view API keys already available within your Google Cloud project, go to the APIs & Services > Credentials page.

Go to Credentials

Use an API key

To use API Gateway features such as quotas, you can pass in an API key so that API Gateway can identify the Google Cloud project that the client application is associated with.

Configure API key authentication for API Gateway

To secure access to your gateway using an API key:

1. Enable API key support for your service. Enter the following command, where:
   • MANAGED_SERVICE_NAME specifies the name of the managed service created when you deployed the API. This can be viewed in the Managed Service property listed with the gcloud api-gateway apis describe command.
   • PROJECT_ID specifies the name of your Google Cloud project.

   gcloud services enable MANAGED_SERVICE_NAME.apigateway.PROJECT_ID.cloud.goog

   For example:

   gcloud services enable my-api-123abc456def1.apigateway.my-project.cloud.goog

2. Modify the OpenAPI specification used to create your API config to include instructions to enforce an API key validation security policy on all traffic. Add the security type and securityDefinitions or securitySchemes as shown:

   OpenAPI 2.0

     # openapi2-functions.yaml
     swagger: '2.0'
     info:
       title: API_ID optional-string
       description: Sample API on API Gateway with a Google Cloud Functions backend
       version: 1.0.0
     schemes:
       - https
     produces:
       - application/json
     paths:
       /hello:
         get:
           summary: Greet a user
           operationId: hello
           x-google-backend:
             address: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/helloGET
           security:
           - api_key: []
           responses:
             '200':
               description: A successful response
               schema:
                 type: string
     securityDefinitions:
       # This section configures basic authentication with an API key.
       api_key:
         type: "apiKey"
         name: "key"
         in: "query"

   The securityDefinition configures your API to require an API key passed as a query parameter named key when requesting access to all paths defined in the spec.

   OpenAPI 3.x

   # openapi-functions.yaml
   openapi: 3.0.4
   info:
     title: API_ID optional-string
     description: Sample API on API Gateway with a Google Cloud Functions backend
     version: 1.0.0
   # Define reusable components in x-google-api-management
   x-google-api-management:
     backend:
       functions_backend:
         address: https://GATEWAY_LOCATION-PROJECT_ID.cloudfunctions.net/helloGET
         pathTranslation: APPEND_PATH_TO_ADDRESS
         protocol: "http/1.1"
   # Apply the backend configuration by referencing it by name. Set at the root so this applies to all operations unless overridden.
   x-google-backend: functions_backend
   components:
   # This section configures basic authentication with an API key.
     securitySchemes:
       google_api_key:
         type: apiKey
         name: x-api-key
         in: header
   security:
     - google_api_key: []
   paths:
     /hello:
       get:
         summary: Greet a user
         operationId: hello
         responses:
           '200':
             description: A successful response
             content:
               application/json:
                 schema:
                   type: string

   The securitySchemes configures your API to require an API key passed as a query parameter named key when requesting access to all paths defined in the spec.

3. Create a new API config with the modified OpenAPI description using the following command:

   gcloud api-gateway api-configs create NEW_CONFIG_ID \
   --api=API_ID --openapi-spec=NEW_API_DEFINITION \
   --project=PROJECT_ID --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL

   For example:

   gcloud api-gateway api-configs create my-config-key \
     --api=my-api --openapi-spec=openapi-functions.yaml \
     --project=my-project --backend-auth-service-account=[e-mail]

4. Run the following command to update your existing gateway with the new API config:

   gcloud api-gateway gateways update GATEWAY_ID \
     --api=API_ID --api-config=NEW_CONFIG_ID \
     --location=GATEWAY_LOCATION --project=PROJECT_ID

   For example:

   gcloud api-gateway gateways update my-gateway \
     --api=my-api --api-config=my-config-key \
     --location=us-central1 --project=my-project

Restricting API keys

By default, API keys are unrestricted, which makes the vulnerable to unauthorized use. Add API restrictions whenever possible. API restrictions specify which APIs can be called using the API key. All API keys used by production applications should have API restrictions.

To add API restrictions:

1. Find the title of the API as noted in your API Config. In the following example, the API title is My Example Config:

   OpenAPI 2.0

   # openapi.yaml
   swagger: '2.0'
   info:
     title: My Example Config
     description: Sample API on API Gateway
     version: 1.0.0
   ...

   OpenAPI 3.x

   # openapi.yaml
   openapi: 3.0.4
   info:
     title: My Example Config
     description: Sample API on API Gateway
     version: 1.0.0
   ...

2. In the Google Cloud console, go to the APIs & Services > Credentials page.

   Go to Credentials

3. Select the name of the API key you want to use for your API.

4. In the API restrictions section of the API key detail page, click Restrict key.

5. Select the API that your API key will be used to access from the drop-down list of available APIs. For example, select My Example Config.

6. Click Save.

Your restriction should take effect momentarily.