API Key Best Practices
As you develop apps that use Google Maps, you will encounter API keys. 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 this API. - Project Authorization.
Check whether the calling app has been granted access to call the API and has enabled the API 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 the key allows Google Maps Platform APIs to reject calls from other projects.
Protecting API keys
You should secure the API keys in your application for all 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 associated with Google Maps Platform products section.
Restrict your API keys to the contexts that need them. By specifying the IP addresses, referrer URLs, or mobile apps associated with each key, you can reduce the impact of a compromised API key.
You can specify the hosts and apps that can use each 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.
- 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, use the following methods to safeguard your apps and API keys:
- Do not embed API keys directly in code. Instead of directly embedding API keys 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 will not be included in the shared files.
- Do not store API keys in files inside your application's source tree. If you store API keys in files, keep the files outside your application's source tree to help ensure your keys 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 or any other private information before you make your code publicly available.
On mobile apps that use Maps Web Service APIs, consider one or more of the following techniques to further safeguard your apps and API keys:
- Apply an API restriction on the API key. This action narrows the scope of the API key to the APIs you associate with the key.
- Obfuscate or encrypt the API key. This action complicates key scraping attempts 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:
Use a proxy server. The proxy server provides a solid source for interacting with the appropriate Maps Platform API. For more information on using a proxy server, see:
How to restrict an API key
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 by specifying an Application restriction, or one or more API restrictions.
Application restrictions associate APIs key with specific sites (IP address and web site) or with specific platforms (Android and iOS). You can select at most one restriction from this category.
API restrictions associate API keys with one or more Maps Platform APIs that an application can access. Requests to use APIs registered with a specified API key will be processed. Requests to use APIs not registered with a specified API key will fail. For an API key, you can specify as many API restrictions as needed.
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.
To associate an API key with a Google Maps Platform API
When you associate an API key with a Google Maps Platform API, the API key will then work only with the API(s) you specify. Follow these steps to restrict 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 API restrictions.
This link is on the same line and to the right of the Application restrictions link. - In the API restrictions list, select a Maps Platform API you want your application to access using the API key.
- If you want to specify more than one Maps Platform API, re-visit the list and select another API to associate with the API key.
- When you finsh selecting APIs, click Save to have your choices recorded.
API key restrictions associated with Google Maps Platform products
The following table lists Google Maps Platform products with the appropriate API key restrictions and best practices for each product.
Maps Platform API Restrictions Best Practices Maps SDK for Android API key with Android restriction1,
API restrictionPlaces SDK for Android API key with Android restriction1,
API restrictionMaps SDK for iOS API key with iOS restriction1,
API restrictionPlaces SDK for iOS API key with iOS restriction1,
API restrictionMaps JavaScript API API key with HTTP referer restriction1 Maps Static API API key with HTTP referer restriction1 + optional3 Digital Signature Street View API API key with HTTP referer restriction1 + optional3 Digital Signature Maps Embed API API key with HTTP referer restriction1 Directions API API key with IP address restriction1,2 Distance Matrix API API key with IP address restriction1,2 Elevation API API key with IP address restriction1,2 Geocoding API API key with IP address restriction1,2 Geolocation API API key with IP address restriction1,2 Roads API API key with IP address restriction1,2 Time Zone API API key with IP address restriction1,2 Places API API key with IP address restriction1,2 1 During development and prototyping, you may use a generic API key (a key with no restrictions) with any Maps Platform API. It's recommended that you secure API keys with restrictions in the following scenarios:
- The test environment will be or is publicly visible.
- Your application that uses an API key is ready to be used in a production environment.
2 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:
3 For Maps Static API and Street View API, you need to enable billing and 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.