API Key Best Practices
API keys are required for apps and projects that use the Google Maps Platform APIs and SDKs. This document identifies the intended use of API keys, how to protect them as you would other credentials, and which restrictions are appropriate for your projects.
What are API keys?
API keys are project-centric credentials that serve two purposes:
- Project Identification.
Identify the app or the project that's making a call to the API or SDK. - Project Authorization.
Check whether the calling app has been granted access to call the API or SDK and has enabled the API or SDK in the project.
When an API key is created, it is associated with a project. By identifying the calling project, an API key enables usage information to be associated with that project, and helps ensure calls from other projects are rejected.
Protecting API keys
You should secure the API keys in your application for all Google Maps Platform products that your application uses. You can secure API keys by designating restrictions and by implementing best practices that are appropriate for the Google Maps Platform APIs in your application. Publicly exposing unsecured credentials can result in unintended use, which could lead to unexpected charges on your account.
The following practices describe strategies to help protect your API keys. The applicable practices for an individual Google Maps Platform product, such as Maps JavaScript API, are listed in the API key restrictions and best practices section.
-
Restrict your API keys. You can best protect your API key by restricting it to specific IP addresses, referrer URLs or mobile apps, and specific APIs, as this significantly reduces the impact of a key compromise.
You can specify application and API restrictions for a key from the console by opening the Credentials page and then either creating a new API key with the settings you want, or editing the settings of an API key. See section Restricting API keys for full details.
- Use independent API keys for different apps. This limits the scope of each key. If an API key is compromised, you can delete and revoke the impacted key without needing to update your other API keys.
- Delete unneeded API keys.
-
Exercise caution when regenerating API keys. If the time needed to migrate your apps from the old API key to the new, regenerated API key exceeds 24 hours, the instances that are not updated will become broken as they reference the old key, which is destroyed 24 hours after regeneration.
When you regenerate an API key, the following things happen:
- A new key results from the regeneration process.
- The new key receives all the restrictions from the old key.
- A 24-hour window begins, marking the amount of time until the old key is destroyed.
-
Monitor usage of your API for anomalies. If you observe unauthorized usage, rotate your keys and notify Google.
Before rotating a key, preserve the restrictions associated with the key by making a copy of them in a file.
-
On apps that use Maps Web Service APIs or Static Web APIs, use the following methods to safeguard your apps and API keys:
- Do not embed API keys or signing secrets directly in code. Instead of directly embedding API keys or any other private information in you application's code, put them in environment variables or in include files that are stored separately from the bulk of your code—outside the source repository of your application. Then, if you share your code, the API keys or signing secrets will not be included in the shared files.
- Do not store API keys or signing secrets in files inside your application's source tree. If you store API keys or any other private information in files, keep the files outside your application's source tree to help ensure your keys or other private information do not end up in your source code control system. This is particularly important if you use a public source code management system such as GitHub.
- Review your code before publicly releasing it. Ensure that your code does not contain API keys, signing secrets or any other private information before you make your code publicly available.
-
On mobile apps that use Web Service APIs or Static Web APIs, consider one or more of the following techniques to further safeguard your API keys or signing secrets:
-
Use a proxy server. The proxy server provides a solid source for interacting with the appropriate Google Maps Platform API. For more information on using a proxy server, see:
- Obfuscate or encrypt the API key or signing secret. This complicates scraping of API keys and other private data directly from the application.
-
Use CA pinning or certificate pinning to verify the server resources are valid. CA pinning checks that a server's certificate was issued by a trusted certificate authority, and prevents Man-In-The-Middle attacks that could lead to a third party discovering your API key. Certificate pinning goes further by extracting and checking the public key included in the server certificate. Pinning is useful for mobile clients communicating directly with Google servers, as well as mobile clients communicating with the developer's own proxy server.
For more information, see:
-
Restricting API keys
API keys are credentials, and you should manage them carefully. At a minimum, follow the recommendations below to keep your keys safe, and to make sure that you have restrictions in place to reduce the impact of compromised API keys.
You can restrict an API key by specifying an Application restriction, or one or more API restrictions.
Application restrictions limit usage of API keys to specific sites (IP address and web site) or specific platforms (Android and iOS). You can select at most one restriction from this category (see Google Maps Platform APIs by Platform).
API restrictions limit usage of API keys to one or more Google Maps Platform APIs or SDKs. Requests to use APIs or SDKs associated with an API key will be processed. Requests to use APIs or SDKs not associated with an API key will fail. For an API key, you can specify as many API restrictions as needed. Make sure the APIs or SDKs associated with an API key support the application restriction set for that API key.
To set an application restriction for an API key
- Visit the credentials panel.
- Select the API key that you want to set a restriction on. The API key property page appears.
- Under Key restrictions, select Application restrictions.
Select one of the restriction types and supply the requested information following the restriction list.Restriction type Description HTTP referrers Accept requests from the list of websites that you supply.
Below the types, specify one or more referrer web sites. Wildcard characters are acceptable for naming similar web sites. For example,
*.google.comaccepts all sites ending ingoogle.com, such ashttps://developers.google.com.IP addresses Accept requests from the list of web server IP addresses that you supply.
Below the types, specify one IPv4 or IPv6 address or a subnet using CIDR notation (e.g. 192.168.0.0/22). If you need to enter another entry, a new box appears after you complete adding the previous entry.
Android apps Add your package name and SHA-1 signing-certificate fingerprint to restrict usage to your Android app.
Below the types, add the SHA-1 signing-certificate fingersprint and your Android package name from your AndroidManifest.xml file.
iOS apps Accept requests from the iOS app with the bundle identifier that you supply.
Below the types, select the appropriate iOS bundle identifier from the list.
- Click Save.
The restriction becomes part of the API key definition after this step. If you fail to provide the appropriate details or do not click “Save”, the API key will not be restricted. (For further information, see the Get an API Key guide for the specific API or SDK you are interested in.)
To set an API restriction for an API key
- Go to the credentials panel.
- Select the API key that you want to restrict.
The Restrict and rename API key page appears. - Under API restrictions:
- Click Restrict key.
- Click the Select APIs drop-down and select the APIs or SDKs you want your application to access using the API key. (If an API or SDK is not listed, you need to enable it.)
- Click Save.
The restriction becomes part of the API key definition after this step. If you fail to provide the appropriate details or do not click “Save”, the API key will not be restricted. (For further information, see the Get an API Key guide for the specific API or SDK you are interested in.)
API key restrictions and best practices
The following table lists the appropriate API key restrictions and best practices for each Google Maps Platform API, SDK or Service.
1 You may use an unrestricted API key with any Google Maps Platform API or SDK. However, it is highly recommended that you restrict your API keys, especially in following scenarios:
- The test environment will be or is publicly visible.
- The application that uses an API key is ready to be used in a production environment.
2 For mobile applications, consider using the native Maps SDK for Android and Maps SDK for iOS.
3 In addition to the API restriction for Maps JavaScript API.
4 For the Maps Static API and Street View Static API, in addition to an API key, you need to provide a digital signature to exceed the daily quota of 25,000 map loads.
Note: Shared secrets used for signing require at least the same level of security as API keys used with Maps Web Service APIs.
Also, if you need to sign your image requests dynamically, do it server side. If your apps rely on client-side input for generating the static images, secure them using one or more of the following techniques:
If you sign your requests, also review how many unsigned requests you wish to allow per day, and adjust your unsigned request quotas accordingly.
5 IP restrictions might be impractical, such as in mobile applications and cloud environments that rely on dynamic IP addresses. When using Maps Web Service APIs in these scenarios, secure your apps using one or more of the following techniques:
6 For mobile applications, consider using the native Places SDK for Android and Places SDK for iOS.