Introduction to API keys
There are two types of API keys: standard API keys, and authorization keys. Both keys let you associate a request with a project for billing and quota purposes. However, they differ in the following way:
A standard API key doesn't authenticate a principal.
An authorization key authenticates as a service account. It operates in a similar fashion to a long-lived access token.
The Credentials page in the Google Cloud console ensures that the correct type of API key is created for a selected API.
Standard API keys
Standard API keys provide a way to associate a request with a project for billing and quota purposes. When you use a standard API key (an API key that has not been bound to a service account) to access an API, the API key doesn't identify a principal. Without a principal, the request can't use Identity and Access Management (IAM) to check whether the caller is authorized to perform the requested operation.
Standard API keys can be used with any API that accepts API keys, unless API restrictions have been added to the key. Standard API keys can't be used with services that don't accept API keys, including in express mode.
Authorization keys
Authorization keys are API keys that are bound to a service account. When you use an authorization key to access an API, your request is processed as if you used the bound service account to make the request.
APIs that support authorization keys include
AI Platform
(aiplatform.googleapis.com) and the
Gemini API
(generativelanguage.googleapis.com).
When using authorization keys, keep the following in mind:
Requests authenticated by authorization keys aren't recorded in service account usage metrics.
Binding keys to a service account is prevented by a default organization policy constraint. To change this, see Enable authorization keys.
API key components
An API key has the following components, which let you manage and use the key:
- String
- The API key string is an encrypted string, for example,
AIzaSyDaGmWKa4JsXZ-HjGw7ISLn_3namBGewQe. When you use an API key to access an API, you always use the key's string. API keys don't have an associated JSON file. - ID
- The API key ID is used by Google Cloud administrative tools to uniquely identify the key. The key ID can't be used to access APIs. The key ID can be found in the URL of the key's edit page in the Google Cloud console. You can also get the key ID by using the Google Cloud CLI to list the keys in your project.
- Display name
- The display name is an optional, descriptive name for the key, which you can set when you create or update the key.
- Bound service account
- Authorization keys include the service account's email address.
Before you begin
Complete the following tasks to use the samples on this page.
Set up authentication
Select the tab for how you plan to use the samples on this page:
Console
When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.
gcloud
In the Google Cloud console, activate Cloud Shell.
At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
C++
To use the C++ samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.
-
Install the Google Cloud CLI.
-
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
-
If you're using a local shell, then create local authentication credentials for your user account:
gcloud auth application-default login
You don't need to do this if you're using Cloud Shell.
If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.
For more information, see Set up ADC for a local development environment in the Google Cloud authentication documentation.
Java
To use the Java samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.
-
Install the Google Cloud CLI.
-
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
-
If you're using a local shell, then create local authentication credentials for your user account:
gcloud auth application-default login
You don't need to do this if you're using Cloud Shell.
If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.
For more information, see Set up ADC for a local development environment in the Google Cloud authentication documentation.
Python
To use the Python samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.
-
Install the Google Cloud CLI.
-
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
-
If you're using a local shell, then create local authentication credentials for your user account:
gcloud auth application-default login
You don't need to do this if you're using Cloud Shell.
If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.
For more information, see Set up ADC for a local development environment in the Google Cloud authentication documentation.
REST
To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.
Install the Google Cloud CLI.
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
For more information, see Authenticate for using REST in the Google Cloud authentication documentation.
Required roles
To get the permissions that you need to manage API keys, ask your administrator to grant you the following IAM roles on your project:
-
Create API keys:
- API Keys Admin (
roles/serviceusage.apiKeysAdmin) - Service Usage Viewer (
roles/serviceusage.serviceUsageViewer)
- API Keys Admin (
-
Create authorization keys. Add the same roles as you use to create API keys, plus:
- Service Account User (
roles/iam.serviceAccountUser) - Service Account API Key Binding Admin (
roles/serviceAccountApiKeyBindingAdmin)
- Service Account User (
For more information about granting roles, see Manage access to projects, folders, and organizations.
You might also be able to get the required permissions through custom roles or other predefined roles.
Enable authorization keys
Before you can create an authorization key, you must do one of the following:
Update the
constraints/iam.managed.disableServiceAccountApiKeyCreationorganization policy constraint to restrict the services that users can create authorization keys for. When creating an authorization key, users must add an API restriction that matches a service allowed by the constraint.Disable the
constraints/iam.managed.disableServiceAccountApiKeyCreationorganization policy constraint.
Changing the organization policy requires an organization resource. Projects without an organization aren't supported.
To change the policy constraint, complete the following instructions.