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.

API keys are generated on the project making the call, and their use can be restricted to a specific environment such as an IP address range, or a specific Android or iOS app. By identifying the calling project, API keys enable usage information to be associated with that project, and they allow Google Maps APIs to reject calls from other projects.

Protecting API keys

When you use API keys in your applications, take care to keep them secure. Publicly exposing your credentials can result in unintended use, which could lead to unexpected charges on your account. To help keep your API keys secure, follow these practices:

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 that 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. If you share your code, the API keys will not accidently 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 API. For more information on using a proxy server, see:
- Living Vicariously: Using Proxy Servers with the Google Data API Client Libraries
- Google Maps Web Services Proxy for Mobile Applications

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 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.com` accepts all sites ending in `google.com`, such as `https://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 an API

When you associate an API key with an API, the scope of the API focuses to work only with the API(s) you specify. Initially, the API key is unrestricted; it has no associations with any API.

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 an API you want your application to access using the API key.
If you want to specify more than one API set, 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 APIs

The table below indicates which key/credential should be used with each Maps API product. The API restrictions in the table include the following types: IP address, HTTP referer, Android, and iOS.

¹ Premium Plan refers to the new Google Maps APIs Premium Plan, which became available in January 2016. If you have a previous Maps APIs for Work or Maps API for Business license, your required credentials may be different than those listed above. Not sure which plan you purchased? Learn how to check your license type.

² During development and prototyping, you may use a generic API key (a key with no restrictions) with any Maps or Places 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.

³ 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:

API restriction
pinning
proxy server
obfuscation

⁴ For Google Static Maps API and Google Street View Image API, if you exceed the daily quota of 25,000 map loads, then the digital signature is required for any excess map loads. Standard Plan users need to enable billing to exceed the quota.

NOTE: Shared secrets used for signing require the same level or a greater level of security as API keys used with Maps Web Service APIs.