GCP Service Account Keys Explained: What They Are, How They Work, and When to Avoid Them

Why this page exists

Service account keys appear throughout GCP documentation, tutorials, and older infrastructure setups. If you are learning GCP, you will encounter them. You may be asked to create one, debug why one is not working, or figure out whether you need one at all.

This page explains what service account keys are, how they work under the hood, what is actually inside the JSON file, and — critically — when you should reach for them versus when a safer alternative is the better call. By the end, you will have a complete mental model of the mechanism and a clear decision framework for when keys are and are not appropriate.

What is a service account key, in plain English

Start with service accounts. A service account is a non-human identity in Google Cloud. It has an email address like ci-deployer@my-project.iam.gserviceaccount.com and it can be granted IAM roles just like a user account can. Applications, pipelines, and automated processes use service accounts to call GCP APIs instead of acting as a person.

Now, a service account on its own is just a record in IAM. To actually prove you are that identity when connecting from outside Google’s infrastructure, you need a credential. A service account key is that credential. It is a file that contains a private cryptographic key. When your code uses this file to make an API call, it signs a request with the private key, Google verifies the signature using the matching public key it holds, and then issues a short-lived access token. That token is what actually authorises the request.

The critical thing to understand: whoever holds the key file can act as that service account. The file itself is the proof of identity. There is no PIN, no MFA, no IP restriction, and no time limit baked into the key. The file is the credential. Full stop.

How service account keys work

The authentication flow is worth understanding step by step. It explains why keys are powerful and why losing one is serious.

1. Key pair created. When you create a service account key, GCP generates an RSA key pair: a private key and a matching public key.

2. Private key delivered to you. The private key is embedded in a JSON file and downloaded to your machine. This is the only moment Google delivers the private key. It is not stored by Google after download.

3. Public key retained by Google. Google stores only the public key on its side, linked to the service account.

4. Your code signs requests. When your application needs to call a GCP API, it uses the private key to sign a short-lived JWT (JSON Web Token) asserting the service account identity.

5. Google verifies the signature. Google checks the JWT signature against the public key it holds. If the signature is valid, it knows the request came from whoever has the private key.

6. Access token issued. Google returns a short-lived OAuth 2.0 access token (typically valid for one hour). Your application uses this token to call GCP APIs.

7. Access is defined by IAM, not the key. What the token can actually do depends entirely on the IAM roles attached to the service account, not anything in the key file itself. The key proves identity. IAM determines what that identity is allowed to do.

What a service account key file contains

When you download a key, you get a JSON file that looks like this (values truncated for readability):

{
  "type": "service_account",
  "project_id": "my-app-prod",
  "private_key_id": "abc123def456...",
  "private_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEA...\n-----END RSA PRIVATE KEY-----\n",
  "client_email": "ci-deployer@my-app-prod.iam.gserviceaccount.com",
  "client_id": "123456789012345678901",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/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/ci-deployer%40my-app-prod.iam.gserviceaccount.com"
}

Here is what each field means and which ones are sensitive:

• private_key: the RSA private key. This is the dangerous field. Anyone with this value can sign authentication requests as the service account. Everything else in the file is non-secret metadata, but this field alone is what makes the file a live credential.

• private_key_id: a unique identifier for this specific key. Used when deleting or auditing keys. Not itself sensitive, but useful for tracking.

• client_email: the service account’s email address. This is the identity that gets used when making API calls. It tells you exactly which service account the key belongs to.

• project_id: the GCP project the service account lives in. Useful context for understanding the blast radius if the key is leaked.

• token_uri: the endpoint used to exchange a signed JWT for an access token. Client libraries use this automatically.

When service account keys are and are not needed

When keys are usually NOT needed

The majority of GCP workloads do not need service account keys, because GCP provides a better mechanism: the metadata server. When you attach a service account to a GCP resource, the metadata server (a special internal endpoint at 169.254.169.254 accessible only from within the resource) automatically provides temporary credentials to code running on that resource. No file download, no secret management, no rotation required.

This applies to all of the following:

• Compute Engine VMs with an attached service account
• Cloud Run services with a specified service account
• Cloud Functions with an assigned service account
• GKE pods using Workload Identity for GKE
• Cloud Build jobs, App Engine services, Dataflow jobs, and other managed runtimes

If your code is already running on GCP, there is almost certainly no reason to use a key. The credentials are already there, managed automatically, rotated automatically, and scoped to the resource they are running on. Using a key in this context adds risk with no benefit.

When keys might still be needed

Keys are occasionally legitimate when a workload cannot use the metadata server or Workload Identity Federation:

• External applications without OIDC support. If a third-party tool needs to call GCP APIs and cannot obtain an OIDC token from a trusted identity provider, a key may be the only option.

• On-premises systems in environments where federation setup is blocked. Some organisations have network or tooling constraints that make federation difficult to configure in the short term.

• Migration windows. During a planned move from key-based auth to federation, keys may remain in place temporarily while the new authentication path is validated.

• Local development against specific service account permissions. In some cases, a developer may need to test code running as a specific service account identity and impersonation is not available in the local environment. This is the weakest justification and should be evaluated carefully.

When you will actually encounter service account keys

Even if keys are rarely the right choice for new infrastructure, you will encounter them in the real world. Understanding where they appear helps you recognise them when auditing, troubleshooting, or inheriting a codebase.

• Legacy CI/CD pipelines. Many pipelines built before Workload Identity Federation existed use a key stored as a CI secret. GitHub Actions, CircleCI, Jenkins, and others all support this pattern. It works, but it carries ongoing key management overhead.

• Terraform or IaC tooling run from local machines. Engineers who run terraform apply locally sometimes authenticate via a key file rather than using Application Default Credentials from gcloud auth application-default login.

• Third-party SaaS integrations. External tools that pull data from BigQuery, write to Cloud Storage, or call GCP APIs are sometimes configured with a service account key because the vendor does not support OIDC federation.

• Data pipeline credentials. Scheduled jobs running on external servers (cron tasks, data loaders, ETL scripts) are sometimes authenticated using a key baked into the server configuration.

• Documentation and tutorials. Many GCP tutorials still use GOOGLE_APPLICATION_CREDENTIALS pointing at a key file to keep the example simple. This is fine for a tutorial but not a pattern to carry into production.

Encountering a key in existing infrastructure is not the same as endorsing the approach. If you inherit a key-based setup, treat it as technical debt worth migrating away from, not as confirmation that keys are the right tool.

Service account keys vs safer alternatives

Before choosing a key, it is worth understanding what the alternatives look like on the dimensions that matter most: whether a secret file is required, how long credentials last, and where each option works.

The metadata server approach and Workload Identity Federation are both keyless. Neither requires storing a long-lived credential anywhere. Service account impersonation is also keyless: it generates temporary credentials on demand from an authenticated caller’s own identity.

Keys sit at the bottom of this hierarchy for a reason. They carry the highest operational overhead and the highest risk. They are the right tool only when the alternatives are genuinely unavailable.

Risks and security implications

Service account keys are treated as high-risk credentials in GCP security guidance. The core reasons are structural, not incidental:

• Portable. Unlike credentials from the metadata server (which only work from the specific resource they are bound to), a key file works from anywhere: a developer laptop, a server in a different cloud, an attacker’s machine.

• No built-in expiry. A key does not rotate itself. It does not expire after 24 hours. It is valid indefinitely unless you explicitly delete it. Most organisations have old keys they have forgotten about.

• Silent to copy. A key is a text file. Copying it leaves no trace. Once a key exists in more than one location, you have no way to know how many copies exist or whether any unauthorised party has seen them.

• Easy to leak accidentally. Developers commit key files to repos, paste them into Slack, embed them in Docker images, or print them in CI logs. Each of these paths has caused real cloud security incidents.

For a detailed look at the specific attack patterns and incident mechanics, see Why Service Account Keys Are Dangerous. That page covers the four structural properties that make keys uniquely risky and the most common real-world leak paths.

How to manage keys safely if you cannot avoid them

If you have evaluated the alternatives and a key is genuinely necessary, treat it with the same rigour you would apply to a production database password. That means:

• Apply least privilege to the service account first. Scope IAM roles to exactly what the workload needs. A key with roles/storage.objectViewer on one bucket is far less dangerous than a key with roles/editor on the whole project.

• One key per workload. Never share a key across multiple applications or environments. This allows individual rotation and limits blast radius if a key leaks.

• Store keys in a secrets manager. Use Secret Manager or an equivalent vault (HashiCorp Vault, AWS Secrets Manager if you are in a multi-cloud setup). Never store key files directly on disk, in code, or in environment variables that could appear in logs.

• Rotate keys on a schedule. Establish a maximum key age (90 days is a common target) and rotate before that deadline. Rotation means creating a new key, updating all consumers to use it, then deleting the old one.

• Delete keys that are no longer in use. An unused key is pure risk. Audit regularly and delete anything without a current documented active consumer.

• Monitor key creation and usage. Set up log-based alerts in Cloud Audit Logs for google.iam.admin.v1.CreateServiceAccountKey events. Any unexpected key creation in a production project warrants immediate investigation.

• Restrict key creation with Organisation Policy. In projects where all workloads use metadata-based or federation-based auth, enforce the iam.disableServiceAccountKeyCreation constraint. This blocks key creation at the API level and prevents accidental or unauthorised key creation.

• Document every key. Record who owns each key, what it is used for, and when it was last reviewed. Without documentation, keys accumulate silently and become impossible to audit meaningfully.

How to create, list, and delete keys

The following commands cover the most common key management operations. Each service account can have up to 10 user-managed keys active at once.

Create a key and download it

This command creates a new key and writes the JSON file to your local machine. The file is downloadable only once. Google does not retain a copy of the private key after this point. Store it immediately in a secrets manager.

gcloud iam service-accounts keys create key.json \
  --iam-account=ci-deployer@my-app-prod.iam.gserviceaccount.com \
  --project=my-app-prod

List all active keys for a service account

Use this to audit which keys exist and how old they are. The output shows the key ID, creation time, and key type. Look for USER_MANAGED keys: those are the ones you created and are responsible for.

gcloud iam service-accounts keys list \
  --iam-account=ci-deployer@my-app-prod.iam.gserviceaccount.com \
  --project=my-app-prod

Delete a key by its ID

Use the key ID from the list output. Deleting a key revokes it immediately. Any system still using it will start getting authentication errors. Confirm that all consumers have switched to a new key before deleting.

gcloud iam service-accounts keys delete KEY_ID \
  --iam-account=ci-deployer@my-app-prod.iam.gserviceaccount.com \
  --project=my-app-prod

Find old keys across a project

This pattern queries audit logs to find all key creation events in a project, which is useful when auditing an unfamiliar environment.

gcloud logging read \
  'protoPayload.methodName="google.iam.admin.v1.CreateServiceAccountKey"' \
  --project=my-app-prod \
  --limit=50 \
  --format='table(timestamp,protoPayload.authenticationInfo.principalEmail,protoPayload.request.name)'

If you hit authentication errors after creating or rotating a key, the troubleshooting authentication errors guide covers the most common failure patterns and how to diagnose them.

Quick decision guide

Use this framework when deciding whether to create a service account key:

• Workload runs on GCP (VM, Cloud Run, Cloud Functions, GKE, etc.) — Attach a service account to the resource. Use the metadata server. No key needed.

• External CI/CD platform that supports OIDC (GitHub Actions, GitLab, CircleCI, etc.) — Use Workload Identity Federation. No key needed.

• Developer running commands locally or testing with a specific service account — Use gcloud auth application-default login for your own identity, or service account impersonation if SA-level credentials are specifically required. No key needed.

• External workload with no OIDC support and no path to federation — A key may be unavoidable. Apply all the safe management practices in the section above before creating one. Document the justification.