For apps and projects that use the Google Maps Platform APIs and SDKs, you
must use API keys or, if supported, Oauth, to prevent unauthorized use and
charges. If you use API keys, for maximum security, restrict your API keys when
you create them. These best practices show you how to restrict them.
In addition to applying application and API key restrictions, follow any
security practices that apply to specific Google Maps Platform products.
For example, see the Maps JavaScript API below in
Recommended application and API restrictions
.
If your API keys are already in use, review the recommendations below in
If you are restricting or regenerating an API key that's in use
.
For more details about digital signatures, see the
Digital Signature Guide
.
Recommended best practices
For increased security and to avoid being billed for unauthorized use, follow
these API security best practices for all Google Maps Platform APIs, SDKs, or
services:
Recommended for all API key uses
Restrict your API keys
Use separate API keys for each app
Delete unused API keys
Check your API key usage
Be careful when regenerating API keys
Additional recommendations for websites using Static Web APIs
Protect apps using Static Web APIs
Additional recommendations for apps using web services
Protect apps using web services
Additional recommendations for iOS and Android mobile applications
Protect mobile apps using web Service or Static Web APIs
If you are restricting or regenerating an API key that's in use
Before you change the API key,
Check your API key usage
This step is especially important if you are adding restrictions after the key
is in use.
After you change the key, update all of your apps with the new API keys, as
needed.
If there is no active abuse of your API key, you can migrate your apps to
multiple new API keys at your own pace, leaving the original API key untouched
until you only see one type of traffic, to which you can then restrict the API
keys with an application restriction. For further instructions, see
Migrate to multiple API keys
.
Monitor the usage over time, and see when specific APIs, platform types, and
domains have migrated off the old API key before you choose to restrict or
delete the old key. For more information, see
Reporting and monitoring
and
Metrics
.
If your API key has been compromised, you want to move more quickly to secure
your API key and stop the abuse. In Android and iOS apps, keys aren't replaced
until customers update their apps. Updating or replacing keys in JavaScript or
web service apps is much more straightforward, but it still may require
careful planning and fast work.
For more information, see
Handle unauthorized use of an API key
.
Restrict your API keys
Best practice is to always restrict your API keys with an application
restriction and one or more API restrictions. For suggested restrictions by API,
SDK, or JavaScript service, see
Recommended application and API restrictions
below.
Application restriction
You can limit the use of an API key to specific
platforms: Android or iOS applications, or specific websites for client-side
applications, or specific IP addresses or CIDR subnets for server-side apps
issuing web service REST API calls.
You restrict a key by adding one or more application restrictions of the types
you want to authorize, after which only requests originating from these
sources are permitted.
API restrictions
You can restrict which Google Maps Platform APIs,
SDKs, or services on which your API key can be used. API restrictions only
allow requests to the APIs and SDKs you specify. For any given API key, you
can specify as many API restrictions as needed. The list of available APIs
includes all APIs enabled on a project.
Set an application restriction for an API key
Open the Google Cloud Console
Google Maps Platform Credentials
page.
Select the API key that you want to restrict.
On the
Edit API key page
, under
Key restrictions
, select
Set an application restriction
.
Select one of the restriction types and supply the requested information
following the restriction list.
Restriction type
|
Description
|
Websites
|
Specify one or more referrer websites.
- The universally-supported referrer URI schemes are
https
and
http
.
- Always provide the
full
referrer URI, including
the protocol scheme, hostname and optional port
(e.g.,
https://google.com
).
- You can use wildcard characters to authorize all subdomains. For
example,
https://*.google.com
accepts all sites ending
in
.google.com
. Note that if you specify
www.domain.com, it acts as a wildcard www.domain.com/*, and
authorizes any subpath on that hostname.
- Be careful when authorizing full-path referrers, for example,
https://google.com/some/path
, as, by default, most
current browsers strip the path from cross-origin requests.
|
IP addresses
|
Specify one or more IPv4 or IPv6 addresses, or subnets using CIDR
notation. The IP addresses must match the source address the
Google Maps Platform servers observe. If you use
network address translation (NAT)
,
this address typically corresponds to your machine's
public
IP address.
|
Android apps
|
Add the Android package name (from the
AndroidManifest.xml
file) and the SHA-1
signing certificate fingerprint of each Android application you want
to authorize. If you use
Play App Signing
, to fetch
the signing certificate fingerprint, see
Working with API Providers
.
If you manage your own signing key, see
Self-signing your application
or refer to the instructions for your build environment.
|
iOS apps
|
Add the bundle identifier of each iOS application you want
to authorize.
|
For recommendations for an application restriction, see
Recommended application Restriction
.
Select
Save
.
Set API restrictions for an API key
Open the Google Cloud Console
Google Maps Platform Credentials
page.
Select the API key that you want to restrict.
On the
Edit API key page
, under
API restrictions
:
Select
Restrict key
.
Open
Select APIs
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. For details, see
To enable one or more APIs or SDKs
.
Select
Save
.
The restriction becomes part of the API key definition after this step.
Be sure you provide the appropriate details and select
Save
to save your
API key restrictions. For further information, see the
Get an API Key
guide in the documentation for the specific API or SDK
you are interested in.
For recommended API restrictions, see
Recommended API Restrictions
.
Check your API key usage
If you're restricting API keys after they've been created, or if you want to see
what APIs are being used by a key so you can restrict them, you want to check
your API key usage. These steps show you in which services and API methods
an API key is being used. If you see any usage beyond
Google Maps Platform services, investigate to determine if you need to add
more restrictions to avoid unwanted use.
You can use the Google Maps Platform Cloud Console Metrics explorer to help
determine which API and application restrictions to apply to your API key:
Determine the APIs that use your API key
The following metrics reports allow you to determine which APIs
are using your API keys. Use these reports to do the following:
- See how your API keys are used
- Spot unexpected usage
- Help verify if an unused key is safe to delete. For information about deleting
an API key, see
Delete unused API keys
.
When applying API restrictions, use these reports to create a list of APIs to
authorize, or to validate automatically-generated API key restriction
recommendations. For more information about recommended restrictions, see
Apply recommended restrictions
. For more information about using
the Metrics explorer, see
Create charts with Metrics explorer
.
Go to the
Google Cloud Console's
Metrics explorer
.
Log in and select the project for the API keys you want to check.
Go to the Metrics explorer page for your type of API:
Inspect each API key:
Select
ADD FILTER
.
Select the
label
credential_id
.
Select the
value
corresponding to the key you want to inspect.
Note which APIs this API key is being used for, and confirm the use is
expected.
Once done, select
Remove filter
delete
at the end of the active filter
line to delete the extra filter.
Repeat for any remaining keys.
Restrict your API keys to only the APIs that are being used.
If you spot unauthorized use, see
Handle unauthorized use of an API key
.
Choose the correct type of application restriction using the Metrics explorer
After you have verified and taken any needed actions to ensure your API key is
only used for the Google Maps Platform services it is using, also
ensure the API key has the correct application restrictions.
If your API key has recommended API key restrictions, apply them. For more
information, see
Apply recommended API key restrictions
.
If your API key doesn't have restriction recommendations, determine the type of
application restriction to apply, based on the reported
platform_type
using
the Metrics explorer:
Go to the
Google Cloud Console's
Metrics explorer
.
Log in and select the project for the APIs you want to check.
Go to this Metrics explorer page:
Metrics explorer
.
Inspect each API key:
Select
ADD FILTER
.
Select the
label
credential_id
.
Select the
value
corresponding to the key you want to inspect.
Once done, select
Remove filter
delete
at the end of the active filter
line to delete the extra filter.
Repeat for any remaining keys.
Once you have the platform type for your API keys, apply the application
restriction for that
platform_type
:
PLATFORM_TYPE_JS
- Apply Website restrictions on the key.
PLATFORM_TYPE_ANDROID
- Apply Android application restrictions on the key.
PLATFORM_TYPE_IOS
- Apply iOS application restrictions on the key.
PLATFORM_TYPE_WEBSERVICE
- You
may
have to rely IP address restrictions on the key, to properly
restrict it. For further options for Maps Static API and
Street View Static API, see
Protect apps using Static Web APIs
.
For further instructions for Maps Embed API, see
Websites with the Maps Embed API
.
- My API key is using multiple platform types
- Your traffic can't be properly secured with just a single API key. You need
to migrate to multiple API keys. For more information, see
Migrate to multiple API keys
.
Use separate API keys for each app
This practice limits the scope of each key. If one API key is compromised, you
can delete or regenerate the impacted key without needing to update your other
API keys. You can create up to 300 API keys per project. For more information,
see
Limits on API keys
.
While one API key per application is ideal for security purposes, you can use
restricted keys on multiple apps as long as they use the same type of
application restriction.
Apply recommended API key restrictions
For some project owners and editors, the Google Cloud Console suggests
specific API key restrictions to unrestricted API keys based on their
Google Maps Platform usage and activity.
If available, recommendations appear as pre-filled options on the
Google Maps Platform Credentials
page.
Reasons you may
not
see a recommendation, or an incomplete one
You are (also) using the API key on other than Google Maps Platform
services. If you see usage on other services,
don't
apply the
recommendation without
first
doing the following:
Verify that the API usage you see in the Google Cloud Console Metrics
explorer is legitimate.
Manually
add
missing services to the list of APIs to be authorized.
Manually
add
any missing application restrictions for the services added
to the API list. If your other added would require a different
type
of
application restrictions, see
Migrate to multiple API keys
.
Your API key is not used in client-side SDKs or APIs.
You use the API key in a low-volume app or website that has not seen usage
over the last 60 days.
You have created a new key very recently, or you have very recently deployed
an existing key in a new app. If this is the case, just wait a few more days
to allow the recommendations to update.
You are using the API key in multiple applications that would require
conflicting types of application restrictions,
or
you are using the same
API key in too many different apps or websites. In either case, as a best
practice, you should migrate to multiple keys. For more details, see
Migrate to multiple API keys
.
Reasons you might see recommendations that are
not
visible in the charts
Your app or website sent only very short traffic bursts. In this case, switch
from a
CHART
view to display a
TABLE
or
BOTH
, as the usage is
still visible in the legend. For more information, see
Toggling the chart's full legends
.
Your traffic is from the Maps Embed API. For instructions, see
Determine the APIs that use your API key
.
The traffic from the app or website is outside the date range available in
the Google Cloud Console Metrics explorer.
To apply recommended restrictions
Open the Google Cloud Console
Google Maps Platform Credentials
page.
If available, select
Apply recommended restrictions
.
Note
: If you don't see any recommended restrictions, see
Set API restrictions for an API key
to set appropriate
restrictions.
Select
Check API usage
to verify which services the API key is being
used on. If you see other than Google Maps Platform services,
pause
to manually review the recommendation steps above. See the troubleshooting
steps at the beginning of section
Apply recommended API key restrictions
.
Double-check that the pre-filled restrictions match the websites and apps
where you expect to use your API key.
Best Practice
: Document and remove any application or API restrictions
that are not affiliated with your services. If something breaks due to an
unexpected dependency, then you can add the required apps or APIs back in.
If you recognize that an app, website or API is clearly missing from your
recommendation, add it manually or wait a couple of days to allow the
recommendation to update.
If you need further help with your suggested recommendation,
contact support
.
Select
Apply
.
What to do if your application gets rejected after applying a recommendation
If you notice that an app or website gets rejected after applying a restriction,
look for the application restriction you need to add in the API response error
message.
For client-side SDKs, see below:
To check your required API restrictions, see
Determine the APIs that use your API key
.
If you are unable to determine which restrictions to apply:
- Document the current restrictions for future reference.
- Remove them temporarily while you investigate the issue. You can check your
usage over time using the steps in
Check your API key usage
.
- If needed,
contact support
.
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. For more
information, see
Check your API key usage
.
To delete an API key:
Open the Google Cloud Console
Google Maps Platform Credentials
page.
Select the API key you want to delete.
Select the
Delete
button near the top of the page.
On the
Delete credential
page, select
Delete
.
Deleting an API key takes a few minutes to propagate. After
propagation completes, any traffic using the deleted API key is rejected.
Be careful when regenerating your API keys
Regenerating an API key creates a new key that has all the old key's
restrictions. This process also starts a 24-hour timer after which the old API
key is deleted.
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, after this time period
elapses, any apps still using the old API key stop working.
Before regenerating an API key
:
First try to restrict your API keys as described in
Restrict your API keys
.
If restricting your API key is not possible due to conflicting application
restriction types, migrate to multiple new (restricted) keys as described in
Migrate to multiple API keys
. Migrating
lets you control the migration and roll out timeline to the new API keys.
If the preceding suggestions aren't possible
, and you must regenerate your
API key to prevent unauthorized use, then follow these steps:
Open the Google Cloud Console
Google Maps Platform Credentials
page.
Open the API key you want to regenerate.
At the top of the page, select
Regenerate key
.
Select
Replace key
.
Note
: If necessary, you can roll back any key that has been regenerated to
its previous version. There are no time limits for roll-back.
To roll back a regenerated key
Open the Google Cloud Console
Google Maps Platform Credentials
page.
Open the API key you want to roll back.
Select
Revert to previous key
.
In the
Revert
dialog, select
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.
If you regenerate the key again, it overwrites the old inactive key value.
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:
Identify which apps 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.
Create and restrict the new keys
: Add both an application restriction
and at least one API restriction. For more information, see
Recommended best practices
.
Add the new keys to your apps
: For mobile apps, this process may
take months until all of your users update to the latest app with the new
API key.
Protect apps using Static Web APIs
Static Web APIs, such as the Maps Static API and
Street View Static API, are similar to web service API calls.
You call both using a simple HTTPS REST API, and you typically generate the API
request URL on the server. However, instead of returning a JSON response, Static
Web APIs generate an image that you can embed in generated HTML code. More
importantly, it is generally the end-user
client
, not the server, that calls
the Google Maps Platform service.
Use a digital signature
As a best practice, always use digital signatures in addition to an
API key. Also, review how many unsigned requests you wish to allow per day and
adjust your unsigned request quotas
accordingly.
For more details about digital signatures, see the
Digital Signature Guide
.
Protect your signing secret
To protect Static Web APIs, don't embed your API signing secrets directly in
code or in the source tree, or expose them in client-side applications. Follow
these best practices for protecting your signing secrets:
Sign your requests server-side, not on the client
. If you do the signing
client-side in JavaScript, you expose it to anyone visiting your site.
Therefore, for dynamically-generated images, always generate your signed Maps
Static API and Street View Static API request URLs server-side when serving
the web page. For static web content, you can use the
Sign a URL now
widget on the Cloud Console Google Maps Platform
Credentials
page.
Store signing secrets outside of your application's source code and source tree
.
If you put your signing secrets or any other private information in
environment variables or include files that are stored separately and then
share your code, then signing secrets are not included in the shared files. If
you store signing secrets or any other private information in files, keep
the files outside your application's source tree to keep your signing secrets
out of your source code control system. This precaution is particularly
important if you use a public source code management system, such as GitHub.
Protect your API key in apps using web services
Store API keys outside of your application's
source code or source tree
. If you put your API keys or any other
information in environment variables or include files that are stored
separately and then share your code, the API keys are not included in the
shared files. This is
particularly
important if you use a public source code
management system, such as GitHub.
Protect your API key and signing secret in mobile apps using web services or Static Web APIs
To protect mobile apps, use a secure keystore or secure proxy server:
Store the API key or signing secret in a secure keystore
. This step makes
it harder to scrape API keys and other private data directly from the
application.
Use a secure proxy server
. The proxy server provides a solid source for
interacting with the appropriate Google Maps Platform API. For more
information about using a proxy server, see
Living Vicariously: Using Proxy Servers with the Google Data API Client Libraries
.
Construct your Google Maps Platform requests on the proxy server.
Don't
allow clients to relay arbitrary API calls via the proxy.
Post-process the Google Maps Platform responses on your proxy server.
Filter out data that the client doesn't need.
Handle unauthorized use of an API key
If you detect use of your API key that is unauthorized, do the following to
address the problem:
Restrict your keys
: If you've used the same key in multiple apps,
migrate to multiple API keys, and use separate API keys for each app.
For more details, see:
Only
regenerate keys if you are unable to restrict them. Read through
section
Be careful when regenerating API keys
before
proceeding.
If you are still having issues or need help,
contact support
.
The following sections suggest appropriate application and API restrictions for
each Google Maps Platform API, SDK or service.
Recommended API Restrictions
The following guidelines for API restrictions apply to the entire
Google Maps Platform:
Some examples:
You are using the Maps SDK for Android and
Places SDK for Android, so you include the
Maps SDK for Android and Places API as
API restrictions.
Your website uses the Maps JavaScript API
Elevation Service and
the Maps Static API, so you add API restrictions for all of the
following APIs:
- Maps JavaScript API
- Elevation API
- Maps Static API
Recommended application Restriction
Websites with Maps JavaScript API or Static Web API
For websites using Maps JavaScript services or Static Web APIs, use the
Websites
application restriction.
Use for websites using these JavaScript services and APIs:
1
For mobile applications, consider
using the native
Maps SDK for Android
and
Maps SDK for iOS
.
2
See also
Protect mobile apps using web service or Static Web APIs
.
Websites with the Maps Embed API
While using the Maps Embed API is free of charge, you should still
restrict any used API key to prevent abuse on
other
services.
Best practice
: Create a separate API key for Maps Embed API
use, and restrict this key to
only
the Maps Embed API. This
restriction sufficiently secures the key, preventing its unauthorized use on any
other Google service.
If you are unable to separate your Maps Embed API usage to a
separate API key, secure your key using the
Websites
application restriction.
Apps and servers using web services
For apps and servers using web services, use the
IP addresses
application restriction.
Use for apps and servers using these APIs:
3
For mobile applications, consider using
the native
Places SDK for Android
and
Places SDK for iOS
.
Android apps
For apps on Android, use the
Android apps
application restriction.
Use for apps and servers using these SDKs:
In addition, prevent accidentally checking API keys into version control by
using the
Secrets Gradle
Plugin
to inject secrets
from a local file rather than storing them in the Android Manifest.
iOS apps
For apps on iOS, use the
iOS apps
application restriction.
Use for apps and servers using these SDKs: