Using API keys

This topic shows application developers how to use API keys with Google Cloud APIs. An API key is a simple encrypted string that identifies an application without any principal. They are useful for accessing public data anonymously, and are used to associate API requests with your project for quota and billing.

To learn more about authenticating to Google Cloud APIs and to determine the best authentication strategy for common scenarios, see Authentication overview. To learn more about using API keys for Google Maps Platform APIs and SDKs, see the Google Maps Platform documentation.

Managing API keys

We recommend you use the Cloud Console to manage API keys. Navigate to the APIs & services → Credentials page in the Cloud Console. Your API keys are shown in the API keys section. On this page, you can create API keys, define API key restrictions, rotate API key strings, and take other actions.

Creating an API key

To create an API key in a project, the user must be granted the Editor basic role (roles/editor) on the project. See basic roles for more information.

To create an API key:

  1. Navigate to the APIs & Services→Credentials panel in Cloud Console.

  2. Select Create credentials, then select API key from the dropdown menu.

  3. The API key created dialog box displays your newly created key.

You might want to copy your key and keep it secure. Unless you are using a testing key that you intend to delete later, add application and API key restrictions.

Using an API key

Pass the API key into a REST API call as a query parameter with the following format. Replace API_KEY with your API key,

key=API_KEY

For example, to pass an API key for a Cloud Natural Language API request for documents.analyzeEntities:

POST https://language.googleapis.com/v1/documents:analyzeEntities?key=API_KEY

Securing an API key

When you use API keys in your applications, ensure that they are kept secure during both storage and transmission. Publicly exposing your credentials can result in your account being compromised, which could lead to unexpected charges on your account. To help keep your API keys secure, follow these best practices:

  • Do not embed API keys directly in code. API keys that are embedded in code can be accidentally exposed to the public. For example, you may forget to remove the keys from code that you share. Instead of embedding your API keys in your applications, store them in environment variables or in files outside of your application's source tree.

  • 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.

  • Set up application and API key restrictions. By adding restrictions, you can reduce the impact of a compromised API key.

  • Delete unneeded API keys to minimize exposure to attacks.

  • Regenerate your API keys periodically. You can regenerate API keys from the Credentials page by clicking Regenerate key for each key. Then, update your applications to use the newly-generated keys. Your old keys will continue to work for 24 hours after you generate replacement keys.

  • 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.

Applying API key restrictions

API keys are unrestricted by default. Unrestricted keys are insecure because they can be used by anyone from anywhere. For production applications, you should set both application restrictions and API restrictions.

To add API key restrictions:

  1. Navigate to the APIs & Services→Credentials panel in Cloud Console.

  2. Select the name of an existing API key.

Adding application restrictions

Application restrictions specify which web sites, IP addresses, or apps can use an API key. Add application restrictions based on your application type. You can only set one restriction type per API key.

Choose the restriction type based on the needs of your application.

  • Use None for testing purposes only.

  • Use HTTP referrers for API clients that run on a web browser, so that only the specified pages can call the API. These types of applications expose their API keys publicly, so we recommend using a service account instead. See the Adding HTTP restrictions section below for examples.

  • Use IP addresses to limit API key access to certain IP addresses.

  • Use Android apps for Android applications. This option requires adding your package name and SHA-1 signing-certificate fingerprint.

  • Use iOS apps for iOS applications. This option requires adding at least one iOS bundle identifier to restrict API calls to specific iOS bundles.

Adding HTTP restrictions

API keys used by web applications should have HTTP restrictions. To add HTTP restrictions:

  • Select HTTP referrers (web sites) in the Application restrictions section.

  • Input at least one restriction in the Website restrictions section.

  • If your domain supports both HTTP and HTTPS, both restrictions must be added separately.

  • You can optionally use wildcard characters (*) for the subdomain and/or path.

The following table shows example scenarios and restrictions, from most restrictive to least restrictive. We recommend using the most restrictive example that fits your use case.

Scenario Restrictions
Allow a specific URL.

Add a single restriction with an exact path. For example:

  • https://www.example.com/path
  • http://www.example.com/path/path
Allow any URL in a single subdomain or naked domain.

You must set at least two restrictions to allow an entire domain.

  1. Set a restriction for the domain, without the trailing slash. For example:
    • https://www.example.com
    • http://sub.example.com
    • http://example.com
  2. Set a second restriction for the domain that includes a wildcard for the path. For example:
    • https://www.example.com/*
    • http://sub.example.com/*
    • http://example.com/*
  3. If your domain allows both HTTP and HTTPS you must add additional restrictions separately.
Allow any subdomain URLs in a single domain.

You must set at least two restrictions.

  1. Set a restriction for the domain, with a wildcard for the subdomain, and without the trailing slash. For example:
    • https://*.example.com
  2. Set a second restriction for the domain that includes a wildcard for the path, such as:
    • https://*.example.com/*
  3. If your domain allows both HTTP and HTTPS you must add additional restrictions separately.

Adding API restrictions

API restrictions specify which APIs can be called using the API key. All API keys used by production applications should have API restrictions.

To set API restrictions:

  1. Select Restrict key in the API restrictions section.

  2. Select all API names that your API key needs to call from the dropdown.

  3. Select the Save button.

What's next