API keys identify your application or website to Google Cloud. API key restrictionsensure that only your apps and websites can use your keys. For security reasons,we recommend that you add restrictions that specify:
- Which clients or websites can use your API keys.
- The Google Cloud APIs that your application can call using yourAPI keys.
If a client uses a restricted API key to issue a request that doesn't satisfythe API key restrictions, then the request fails. For example, if an API keyrequires HTTP requests to be issued from a specific domain but an HTTP requestis received from a different domain, the request will be rejected with an error.
You can add restrictions when you create an API key with the CreateKey method,or you can add the restrictions after the key is created using the UpdateKeymethod. This page describes the restrictions that you can add to an API key, andit shows you how to add those restrictions.
Before you begin
The page uses curl and the Google Cloud CLI to send requests to theAPI Keys API. SeeGetting started with the API Keysfor details on getting set up to experiment with the API.
Adding client restrictions
Client restrictions specify which websites, IP addresses, or apps can use an APIkey. You add client restrictions based on the type of client that calls yourAPI. You can specify one of the following types of client restrictions:
browserKeyRestrictions: The HTTP referrers (websites) that are allowed touse the key.serverKeyRestrictions: The IP addresses of callers that are allowed touse the key.androidKeyRestrictions: The Android apps that are allowed to use the key.iosKeyRestrictions: The iOS apps that are allowed to use the key.
Adding browser restrictions
The following example shows how to call the UpdateKey method to restrict theHTTP referrer to www.example.com:
gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID?updateMask=restrictions \ --request PATCH \ --data '{ "restrictions" : { "browserKeyRestrictions": { "allowedReferrers": "www.example.com" } }, "etag": "ETAG" }'When the response from operations.get contains "done": true, the responsecontains the updated Key with the restrictions.
The following example shows how to create a new API key that only allows HTTPrequests from a list of specific URLs.
gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys \ --request POST \ --data '{ "displayName" : "API key with browser restrictions", "restrictions" : { "browserKeyRestrictions": { "allowedReferrers": ["www.example.com", "www.example-2.com"] } } }'The following table shows some example scenarios and browser restrictions:
| Scenario | Restrictions |
|---|---|
| Allow any URL in your site | You must set two URLs in the allowedReferers list.
|
| Allow a specific URL | Add a URL with an exact path. For example:www.example.com/pathwww.example.com/path/path |
| Allow any URL in a single subdomain or naked domain | You must set two URLs in the `allowedReferers` list to allow an entire domain.
|
Adding server restrictions
You can specify one or more IP addresses of the callers, for example webservers or cron jobs, that are allowed to use your API key. You can specify theIP addresses in any of the following formats:
- IPv4 (
198.51.100.1) - IPv6 (
2001:db8::1) - A subnet using CIDR notation (
198.51.100.0/24,2001:db8::/64)
The following example shows how to create an API key with a list ofallowedIps:
gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys \ --request POST \ --data '{ "displayName" : "API key with server restrictions with IPv4, IPv6 and CIDR", "restrictions" : { "serverKeyRestrictions": { "allowedIps": ["198.51.100.1","198.51.100.0/24","2001:db8::1","2001:db8::/64"] } } }'Adding Android restrictions
You can restrict usage of an API key to only your Android apps. When you createor update an API key, provide the package name and the 20 byteSHA-1 fingerprintfor each app.
For example, assume that you ran thekeytool utilityand it created the following fingerprint:
Certificate fingerprint: SHA1: DA:39:A3:EE:5E:6B:4B:0D:32:55:BF:EF:95:60:18:90:AF:D8:07:09The following example shows how to create an API key with the fingerprint andand package name to the androidKeyRestrictions:
gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys \ --request POST \ --data '{ "displayName" : "API key with Android restrictions", "restrictions" : { "androidKeyRestrictions": { "allowedApplications": [ { "sha1Fingerprint": "DA:39:A3:EE:5E:6B:4B:0D:32:55:BF:EF:95:60:18:90:AF:D8:07:09", "packageName": "com.example.my.app" } ] } } }'Adding iOS restrictions
You can restrict usage of an API key to only your iOS apps by providing thebundle ID of each app when you create or update a key. The following exampleshows how to set the iosKeyRestrictions when creating an API key:
gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys \ --request POST \ --data '{ "displayName" : "API key with iOS restrictions", "restrictions" : { "iosKeyRestrictions": { "allowedBundleIds": ["com.example.my.app1", "com.example.my.app2"] } } }'Adding API restrictions
API restrictions allow you to specify which Google Cloud APIs can be calledusing the API key. We recommend that you add both client and API restrictionsto all your API keys.
You can specify one or more services in the API restrictions. The followingexample shows how to restrict the usage of a new API key to onlythe services translate.googleapis.com and datastore.googleapis.com:
gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys \ --request POST \ --data '{ "restrictions": { "api_targets": [ { "service": "translate.googleapis.com" }, { "service" : "datastore.googleapis.com" } ] }, }'To get a list of services that are enabled in yourGoogle Cloud project, use the gcloud services listcommand.
In addition to restricting the API key for use tospecific services, you can optionally specify the methods in each service tofurther restrict the API key. The following example shows how to restrict theprevious key to only allowed methods of translate.googleapis.com:
gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID?updateMask=restrictions \ --request PATCH \ --data '{ "restrictions": { "api_targets": [ { "service": "translate.googleapis.com" "methods": [ "Get*", "DetectLanguage" ] }, { "service" : "datastore.googleapis.com" } ] }, "etag": "ETAG" }'What's next
- Viewing Cloud Audit Logs
- Troubleshooting
