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.

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:

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
```

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.

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= 0000000000000compute@developer.gserviceaccount.com

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:

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

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

Go to Credentials
Select the name of the API key you want to use for your API.
In the API restrictionssection of the API key detail page, click Restrict key.
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 .
Click Save.

Your restriction should take effect momentarily.