API security best practices

API keys are required for apps and projects that use the Google Maps Platform APIs and SDKs. For maximum security and minimal effort, secure your API keys when you create them.

While it is possible to secure API keys after they're created and in use, there can be different constraints based on how the key is used. Updating or replacing keys in mobile apps (Android and iOS) are the most complicated, since the keys won't all be replaced until all customers update their apps. Updating or replacing keys in JavaScript or Web Service apps are much more straightforward, but updating or replacing these keys still may require careful planning and fast work.

Security practices applicable to the individual Google Maps Platform product, such as Maps JavaScript API, are listed in the More information section.

Restrict your API keys

When you first create your API keys, restrict them with an application restriction, and one or more API restrictions.

  • Application restrictions limit an API key’s usage to a specific platform (Android or iOS) or specific sites (public IP address and web site). Only one type of application restriction may be added to any individual API key.

  • API restrictions limit usage of API keys to one or more Google Maps Platform APIs or SDKs. Only requests to use APIs or SDKs associated with an API key will be processed. For any given API key, you can specify as many API restrictions as needed.

If you did not secure your API key when you created it, create additional API keys and restrict them, then update all of your apps with the new API keys. While one key per application would be ideal for security purposes, you can use restricted keys on multiple apps as long as the types of app restrictions on the key would not cause incompatibility issues with the apps that share a key.

If you’re restricting API keys after they’ve been created, check the API key usage to make sure that the restrictions won’t break any of your existing apps.

  1. Go to the Google Cloud Console's Metrics page.

  2. Select Show filters.

  3. From Grouped By, select Credential. You will see which API keys are used with which Google services.

  4. Click Credentials.

  5. Deselect all credentials.

  6. For each key displayed, select the key and click Ok.

  7. From Grouped By, select API. You will see which API restrictions to apply on the key.

    Selecting API method from Grouped By may give you clues about which application restriction type is best suited for a key.

Set an application restriction for an API key

  1. Go to the Credentials page.
  2. Select the API key that you want to set a restriction on. The API key property page appears.

  3. 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 referers Specify one or more referer web sites. Wildcard characters are acceptable for authorizing all subdomains (for example, *.google.com accepts all sites ending in .google.com). Specify https:// and http:// as-is. You must use a special representation for other types of referer URL protocols. For example, format file:///path/to/ as __file_url__//path/to/*. After enabling referers, be sure to monitor your usage, to make sure it matches your expectations. The following referer protocols are supported: about://, app://, applewebdata://, asset://, chrome://, content://, file://, ftp://, ionic://, local://, ms-appx://, ms-appx-web://, ms-local-stream://, prism://, qrc://, res://, saphtmlp://.
    IP addresses Specify one IPv4 or IPv6 address or a subnet using CIDR notation. Since a web service request checks and compares the external IP address against the API key restriction,use the server's public IP address.
    Android apps Add your SHA-1 signing-certificate fingerprint and your Android package name from your AndroidManifest.xml file.
    iOS apps Below the types, select the appropriate iOS bundle identifier from the list.
  4. Select Save.

Set an API restriction for an API key

  1. Go to the credentials page.

  2. Select the API key that you want to restrict. The Restrict and rename API key page appears.

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

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

Delete unused API keys

Before you delete an API key, make sure that it is not used in production. If there is no successful traffic, the key is likely safe to delete.

To delete an API key:

  1. Go to the Credentials page.

  2. Select the API key you want to delete.

  3. Select the Delete button near the top of the page.

  4. When the Delete credential dialog appears, select Delete.

    Deleting an API key takes a few minutes to propagate. After propagation, traffic using the deleted API key will be rejected.

Other ways to secure your APIs

Be careful when regenerating API keys

Regenerating an API key creates a new key that has all the old key’s restrictions. This also starts a 24-hour timer to deactivate the old API key.

During this time window, both the old and new key are accepted, giving you a chance to migrate your apps to use the new key. However, any apps still using the old API key will stop working after this period elapses.

  1. Go to the API keys page.

  2. Select Revert to previous key.

  3. In the Revert dialog, click Revert key.

Upon rolling back, the former "new" version of the key becomes the previous version, and a new 24-hour deactivation timer is set for it. It is possible to revert between these two key values until you regenerate the key again.

This second regeneration overwrites the old inactive key value.

Monitor your API usage

To check your API key usage:

  1. Go to the Metrics page.

  2. Click Show filters.

  3. From Grouped by, select API method.

  4. Under Response code, select 2xx to see any successful requests to this key.

If you detect unauthorized usage, do the following:

  1. Restrict your keys.

    If the same key is used in multiple apps, migrate to multiple API keys, preferably using separate API keys for each app.

  2. If the unauthorized usage continues, regenerate or delete the affected keys.

  3. Contact support.

Use separate API keys for each app

This limits the scope of each key. If an API key is compromised, you can delete or regenerate the impacted key without needing to update your other API keys.

Migrate to multiple API keys

To migrate from using one API key for multiple apps, to a single unique API key for each app, do the following:

  1. Identify which apps will need new keys.

    • Web apps are the easiest to update, since you control all of the code. Plan to update all of your web-based apps' keys.
    • Mobile apps are much harder, since your customers must update their apps before the new keys can be used.
  2. Create and restrict the new keys.

    • Add both an application restriction and at least one API restriction.
  3. Add the new keys to your various apps.

    • For mobile apps, this process may take months for all of your users to update to the latest app with the new API key.

Maps Web Service APIs or Static Web APIs app protection methods

  • Store API keys and signing secrets outside of your application’s source code. If you put your API keys or any other private information in environment variables or include files that are stored separately and then share your code, the API keys or signing secrets will not be included in the shared files.

  • Store API keys or signing secrets in files outside of 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 keep your keys out of your source code control system. This is particularly important if you use a public source code management system, such as GitHub.

Web Service APIs or Static Web APIs mobile app protection methods

More information

These tables list the appropriate API key restrictions and API security best practices for each Google Maps Platform API, SDK or service.

Websites with Maps JavaScript, Embed or Static APIs

API/SDK/Service Application Restriction (1) API Restriction (1) Best Practices
Maps JavaScript API (2) HTTP referer restriction Maps JavaScript API
Directions Service, Maps JavaScript API HTTP referer restriction Directions API, Maps JavaScript API
Distance Matrix Service, Maps JavaScript API HTTP referer restriction Distance Matrix API, Maps JavaScript API
Elevation Service, Maps JavaScript API HTTP referer restriction Elevation API, Maps JavaScript API
Geocoding Service, Maps JavaScript API HTTP referer restriction Geocoding API, Maps JavaScript API
Places Library, Maps JavaScript API HTTP referer restriction Places API, Maps JavaScript API
Maps Embed API HTTP referer restriction Maps Embed API
Maps Static API HTTP referer restriction Maps Static API
Street View Static API HTTP referer restriction Street View Static API

Apps and servers using web services

API/SDK/Service Application Restriction (1) API Restriction (1) Best Practices
Address Validation API IP address restriction(4) Address Validation API
Directions API IP address restriction(4) Directions API
Distance Matrix API IP address restriction(4) Distance Matrix API
Elevation API IP address restriction(4) Elevation API
Geocoding API IP address restriction(4) Geocoding API
Geolocation API IP address restriction(4) Geolocation API
Places API (5) IP address restriction(4) Places API
Roads API IP address restriction(4) Roads API
Routes API IP address restriction(4) Routes API
Time Zone API IP address restriction(4) Time Zone API

Android apps

API/SDK/Service Application Restriction (1) API Restriction (1) Best Practices
Maps SDK for Android Android restriction Maps SDK for Android
Places SDK for Android Android restriction Places API

iOS apps

API/SDK/Service Application Restriction (1) API Restriction (1) Best Practices
Maps SDK for iOS iOS restriction Maps SDK for iOS
Places SDK for iOS iOS restriction Places API

1 You may use an unrestricted API key with any Google Maps Platform API or SDK. However, we strongly recommend 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 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.

If you sign your requests, review how many unsigned requests you wish to allow per day and adjust your unsigned request quotas accordingly.

4 IP restrictions might be impractical in some scenarios, 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 a proxy server or obfuscation.

5 For mobile applications, consider using the native Places SDK for Android and Places SDK for iOS.