This page explains how to create and manage service account keys using the
Google Cloud Console, the gcloud
command-line tool,
the Cloud Identity and Access Management API, or one
of the Google Cloud Client Libraries.
Prerequisites for this guide
- Understand service accounts
- Install the
gcloud
tool
Required permissions
To allow a user to manage service account keys, grant the Service Account Key
Admin role (roles/iam.serviceAccountKeyAdmin
). Cloud IAM
primitive roles also contain permissions to manage service account keys, but we
recommend granting this role instead to prevent unnecessary access to other
Google Cloud resources.
For more information, see the list of Service Accounts roles.
Creating service account keys
To use a service account outside of Google Cloud, such as on other platforms or on-premises, you must first establish the identity of the service account. Public/private key pairs provide a secure way of accomplishing this goal.
You can create a service account key
using the Cloud Console, the gcloud
tool, the
serviceAccounts.keys.create()
method, or one of the client libraries.
In the examples below, [SA-NAME] is the name of your service account, and [PROJECT-ID] is the ID of your Google Cloud project. You can retrieve the [SA-NAME]@[PROJECT-ID].iam.gserviceaccount.com string from the Service Accounts page in the Cloud Console.
Console
-
Open the IAM & Admin page in the Cloud Console.
- Select your project and click Continue.
- In the left nav, click Service accounts.
- Look for the service account for which you wish to create a key, click the More button in that row, and then click Create key.
- Select a Key type and click Create.
gcloud command
Execute the
gcloud
iam service-accounts keys create
command to create service
account keys.
Command:
gcloud iam service-accounts keys create ~/key.json \
--iam-account [SA-NAME]@[PROJECT-ID].iam.gserviceaccount.com
Output:
created key [e44da1202f82f8f4bdd9d92bc412d1d8a837fa83] of type [json] as
[/usr/home/username/key.json] for
[SA-NAME@PROJECT-ID.iam.gserviceaccount.com]
REST API
Request:
POST https://iam.googleapis.com/v1/projects/[PROJECT-ID]/serviceAccounts/[SA-NAME]@[PROJECT-ID].iam.gserviceaccount.com/keys
Response:
{
"name":"projects/PROJECT-ID/serviceAccounts/SA-NAME@PROJECT-ID.iam.gserviceaccount.com/keys/90c48f61c65cd56224a12ab18e6ee9ca9c3aee7c",
"privateKeyType": "TYPE_GOOGLE_CREDENTIALS_FILE",
"privateKeyData":"MIIJqAIB . . .",
"validBeforeTime": "2028-05-08T21:00:00Z",
"validAfterTime": "2016-01-25T18:38:09.000Z",
"keyAlgorithm": "KEY_ALG_RSA_2048"
}
C#
Before trying this sample, follow the C# setup instructions in the Cloud IAM Quickstart Using Client Libraries . For more information, see the Cloud IAM C# API reference documentation .
Go
Before trying this sample, follow the Go setup instructions in the Cloud IAM Quickstart Using Client Libraries . For more information, see the Cloud IAM Go API reference documentation .
Java
Before trying this sample, follow the Java setup instructions in the Cloud IAM Quickstart Using Client Libraries . For more information, see the Cloud IAM Java API reference documentation .
Python
Before trying this sample, follow the Python setup instructions in the Cloud IAM Quickstart Using Client Libraries . For more information, see the Cloud IAM Python API reference documentation .
Note that the privateKeyData
returned is a base64-encoded string
representation of the TYPE_GOOGLE_CREDENTIALS_FILE
value (JSON or P12
key/credentials).
When you create a key, your new public/private key pair is generated and downloaded to your machine; it serves as the only copy of the private key. You are responsible for storing the private key securely. Take note of its location and ensure the key is accessible to your application; it needs the key to make authenticated API calls.
It may take up to 60 seconds before a newly created key can be used for authentication. If you experience authentication failures immediately after creating a new key, ensure that 60 seconds have elapsed before trying again.
The format of the key may differ depending on how it is generated. Keys created
using the Cloud Console or the gcloud
command-line tool look like
this:
{
"type": "service_account",
"project_id": "[PROJECT-ID]",
"private_key_id": "[KEY-ID]",
"private_key": "-----BEGIN PRIVATE KEY-----\n[PRIVATE-KEY]\n-----END PRIVATE KEY-----\n",
"client_email": "[SERVICE-ACCOUNT-EMAIL]",
"client_id": "[CLIENT-ID]",
"auth_uri": "https://accounts.google.com/o/oauth2/auth",
"token_uri": "https://accounts.google.com/o/oauth2/token",
"auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
"client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/[SERVICE-ACCOUNT-EMAIL]"
}
Whereas keys generated with the REST API or client libraries look like this:
{
"name": "projects/[PROJECT-ID]/serviceAccounts/[SERVICE-ACCOUNT-EMAIL]/keys/[KEY-ID]",
"privateKeyType": "TYPE_GOOGLE_CREDENTIALS_FILE",
"privateKeyData": "[PRIVATE-KEY]",
"validAfterTime": "[DATE]",
"validBeforeTime": "[DATE]",
"keyAlgorithm": "KEY_ALG_RSA_2048"
}
Note once again that the privateKeyData
returned is a base64-encoded string
representation of the TYPE_GOOGLE_CREDENTIALS_FILE
value (JSON or P12
key/credentials).
Because the formatting differs between each method, it's easiest to generate a
key using the same method you plan to use when making future API calls. For
example, if you're using gcloud
, also generate your key using gcloud
. To use
a key for one method that's been generated using a different method (such as
using a REST-generated key with gcloud
), you'll need to edit the
key to match the appropriate format.
Google ensures that all public keys for all service accounts are publicly accessible by anyone and available to verify signatures that are created with the private key. The public key is publicly accessible at the following URLs:
- x.509 certificate: https://www.googleapis.com/service_accounts/v1/metadata/x509/[SA-NAME]@[PROJECT-ID].iam.gserviceaccount.com
- JSON web key (JWK): https://www.googleapis.com/service_accounts/v1/jwk/[SA-NAME]@[PROJECT-ID].iam.gserviceaccount.com
- Raw endpoint: https://www.googleapis.com/service_accounts/v1/metadata/raw/[SA-NAME]@[PROJECT-ID].iam.gserviceaccount.com
Listing service account keys
You can list the service account keys for a service account using the
Cloud Console, the gcloud
tool, the
serviceAccount.keys.list()
method, or one of the client libraries.
The serviceAccount.keys.list()
method is commonly used to audit service
accounts and keys, or to build custom tooling for managing service accounts.
To find out which project your key belongs to, you can download the key as a JSON file and look at that file.
You may see keys listed that you did not create. These are Google Cloud-managed keys used by Google Cloud services such as App Engine and Compute Engine. For more information on the difference between user and Google Cloud-managed keys, see Understanding service accounts.
Console
-
Open the IAM & Admin page in the Cloud Console.
- Select your project and click Continue.
- In the left nav, click Service accounts. All service accounts and their corresponding keys are listed.
gcloud command
Execute the
gcloud iam
service-accounts keys list command to list service
account keys.
Command:
gcloud iam service-accounts keys list \
--iam-account [SA-NAME]@[PROJECT-ID].iam.gserviceaccount.com
Output:
KEY_ID | CREATED_AT | EXPIRES_AT |
8e6e3936d7024646f8ceb39792006c07f4a9760c | 2016-01-26T21:01:42.000Z | 2026-01-23T21:01:42.000Z |
937c98f870f5c8db970af527aa3c12fd88b1c20a | 2016-01-26T20:55:40.000Z | 2026-01-23T20:55:40.000Z |
REST API
Call
serviceAccount.keys.list()
to list a service account's keys.
Request:
GET https://iam.googleapis.com/v1/projects/[PROJECT-ID]/serviceAccounts/[SA-NAME]@[PROJECT-ID].iam.gserviceaccount.com/keys
Response:
{
"keys": [
{
"name": "projects/PROJECT-ID/serviceAccounts/SA-NAME@PROJECT-ID.iam.gserviceaccount.com/keys/90c48f61c65cd56224a12ab18e6ee9ca9c3aee7c",
"validAfterTime": "2016-01-25T18:38:09.000Z",
"validBeforeTime": "2026-01-22T18:38:09.000Z",
"keyAlgorithm": "KEY_ALG_RSA_2048"
},
{
"name": "projects/PROJECT-ID/serviceAccounts/SA-NAME@PROJECT-ID.iam.gserviceaccount.com/keys/e5e3800831ac1adc8a5849da7d827b4724b1fce8",
"validAfterTime": "2016-01-25T13:43:27.000Z",
"validBeforeTime": "2016-01-26T13:43:27.000Z",
"keyAlgorithm": "KEY_ALG_RSA_2048"
},
{
"name": "projects/PROJECT-ID/serviceAccounts/SA-NAME@PROJECT-ID.iam.gserviceaccount.com/keys/b97699f042b8eee6a846f4f96259fbcd13e2682e",
"validAfterTime": "2016-01-26T13:28:27.000Z",
"validBeforeTime": "2016-01-27T13:28:27.000Z",
"keyAlgorithm": "KEY_ALG_RSA_2048"
}
]
}
C#
Before trying this sample, follow the C# setup instructions in the Cloud IAM Quickstart Using Client Libraries . For more information, see the Cloud IAM C# API reference documentation .
Go
Before trying this sample, follow the Go setup instructions in the Cloud IAM Quickstart Using Client Libraries . For more information, see the Cloud IAM Go API reference documentation .
Java
Before trying this sample, follow the Java setup instructions in the Cloud IAM Quickstart Using Client Libraries . For more information, see the Cloud IAM Java API reference documentation .
Python
Before trying this sample, follow the Python setup instructions in the Cloud IAM Quickstart Using Client Libraries . For more information, see the Cloud IAM Python API reference documentation .
Getting a service account key
You can only get the private key data for a service account key when the key is first created.
You can get basic information about a key such as its ID, algorithm, and public
key data with the
projects.serviceAccounts.keys.get()
REST API method. Using the Cloud Console or the gcloud
command-line
tool is not supported.
Uploading public keys for service accounts
You can upload a public key portion of a user-managed key pair to sign service account keys. The public key data is permanently associated with the service account, and will be used for all subsequent signing operations when you create service account keys. If you wish to disable the ability to upload keys for your project, see restricting service account key upload.
If you choose to use a user-managed key pair instead of a Google-managed key pair, ensure that you maintain it and regularly rotate it.
Before uploading your public key, ensure that it is in the
RSA_X509_PEM format. If
you do not yet have an existing certificate, you can generate a self-signed
X.509 in the appropriate format using tools such as
openssl
. To generate a valid certificate using the
openssl
tool:
openssl req -x509 -nodes -newkey rsa:2048 -keyout /output/path/to/private/key \
-out /output/path/to/public/key -subj "/CN=unused"
Note that by default, X.509 certificates created using openssl
expire after 30
days. However, you can extend or shorten the expiration time using the -n
flag.
gcloud command
Execute the
gcloud
alpha iam service-accounts keys upload
command to upload a
public key for signing service account keys.
Command:
gcloud alpha iam service-accounts keys upload /path/to/public/key \
--iam-account [SA-NAME]@[PROJECT-ID].iam.gserviceaccount.com
The output contains a unique identifier for the uploaded key:
Name: projects/PROJECT-ID/serviceAccounts/SA-NAME@PROJECT-ID.iam.gserviceaccount.com/keys/c7b74879da78e4cdcbe7e1bf5e129375c0bfa8d0
To determine whether the command was successful, execute the
gcloud
iam service-accounts keys list
command:
gcloud iam service-accounts keys list \
--iam-account [SA-NAME]@[PROJECT-ID].iam.gserviceaccount.com
The output will contain the same unique identifier that was returned after the key was created:
KEY_ID | CREATED_AT | EXPIRES_AT |
c7b74879da78e4cdcbe7e1bf5e129375c0bfa8d0 | 2019-06-26T21:01:42.000Z | 2029-06-23T21:01:42.000Z |
REST API
Call
serviceAccount.keys.upload()
to upload a public key for a service account.
Request:
POST https://iam.googleapis.com/v1/projects/[PROJECT-ID]/serviceAccounts/[SA-NAME]@[PROJECT-ID].iam.gserviceaccount.com/keys:upload
Request body:
{
"publicKeyData": "LS0tLS1CRUdJTiBDRVJUSUZJQ...jlsCjVjMXUzVlVqS3AtLS0tXG4="
}
The request body must contain the public key data in
RSA_X509_PEM
format.
Response:
{
"name": "projects/[PROJECT-ID]/serviceAccounts/[SERVICE-ACCOUNT-EMAIL]/keys/c7b74879da78e4cdcbe7e1bf5e129375c0bfa8d0",
"keyAlgorithm": "KEY_ALG_RSA_2048",
"keyOrigin": "USER_PROVIDED",
}
Deleting service account keys
You can delete a service account key using the Cloud Console, the
gcloud
tool, the
serviceAccount.keys.delete()
method, or one of the client libraries.
If you delete a key, your application will no longer be able to access Cloud
Platform resources using that key. A security best practice is to rotate your
service account keys regularly. You can rotate a key by creating a new key,
switching applications to use the new key and then deleting old key. Use the
serviceAccount.keys.create()
method and serviceAccount.keys.delete()
method
together to automate the rotation.
Console
-
Open the IAM & Admin page in the Cloud Console.
- Select your project and click Continue.
- In the left nav, click Service accounts. All service accounts and their corresponding keys are listed.
- Click the desired service account's email to view its keys.
- From the list of keys, click Delete for each key you'd like to delete.
gcloud command
Execute the
gcloud
iam service-accounts keys delete
command to delete service
account keys.
Command:
gcloud iam service-accounts keys delete [KEY-ID] \
--iam-account [SA-NAME]@[PROJECT-ID].iam.gserviceaccount.com
Output:
Deleted key [8e6e3936d7024646f8ceb39792006c07f4a9760c] for
service account [SA-NAME@PROJECT-ID.iam.gserviceaccount.com]
REST API
Request:
DELETE https://iam.googleapis.com/v1/projects/[PROJECT-ID]/serviceAccounts/[SA-NAME]@[PROJECT-ID].iam.gserviceaccount.com/keys/[KEY-ID]
C#
Before trying this sample, follow the C# setup instructions in the Cloud IAM Quickstart Using Client Libraries . For more information, see the Cloud IAM C# API reference documentation .
Go
Before trying this sample, follow the Go setup instructions in the Cloud IAM Quickstart Using Client Libraries . For more information, see the Cloud IAM Go API reference documentation .
Java
Before trying this sample, follow the Java setup instructions in the Cloud IAM Quickstart Using Client Libraries . For more information, see the Cloud IAM Java API reference documentation .
Python
Before trying this sample, follow the Python setup instructions in the Cloud IAM Quickstart Using Client Libraries . For more information, see the Cloud IAM Python API reference documentation .