GCP credentials.json — The Complete Guide for 2025–2026

By Agnes Editorial · Updated July 2026 · 14 min read

What Is a GCP credentials.json File?

A credentials.json file is a downloadable key bundle created inside a Google Cloud Service Account. It is the primary mechanism by which applications authenticate to Google Cloud Platform without human intervention. The file contains a JSON object with fields that Google Cloud client libraries expect to perform OAuth2-based sign-in.

The canonical schema looks like this:

{
  "type": "service_account",
  "project_id": "my-gcp-project",
  "private_key_id": "a1b2c3d4...",
  "private_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEpA...",
  "client_email": "deployer@my-gcp-project.iam.gserviceaccount.com",
  "client_id": "112233445566778899",
  "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/deployer%...","
  "universe_domain": "googleapis.com"
}

Every field has a specific purpose. The private_key is an RSA or ECDSA key used to sign JWT access tokens. The token_uri points Google OAuth infrastructure to validate those tokens. The client_email ties the key back to a service account whose IAM roles determine what the application can do.

Google provides two key formats: JSON (the default) and P12 (PKCS12 bundle). The JSON format is what 99% of modern tooling expects. Client libraries for Node.js, Python, Go, Java, and .NET all accept a GOOGLE_APPLICATION_CREDENTIALS environment variable pointing to this file.

Where credentials.json Is Used

• Server-side applications running in Compute Engine, GKE, Cloud Run, or on-premises infrastructure.
• CI/CD pipelines such as Cloud Build, GitHub Actions, and GitLab CI deploying to GCP.
• Local development when engineers run gcloud auth application-default login or manually set the credentials path.
• Third-party tools like Terraform, Pulumi, dbt, and Kubernetes operators that call Google APIs on your behalf.

How credentials.json Authenticates to Google Cloud

The authentication flow follows the standard OAuth2 client-credentials pattern with Google-specific extensions:

1. The client library reads the JSON key and extracts the private_key and client_email.
2. It constructs a JWT containing the audience (token_uri), scope, subject (optional), and expiration (default 1 hour).
3. The JWT is signed with the service account's private key.
4. The signed JWT is exchanged at https://oauth2.googleapis.com/token for an access token.
5. Subsequent API calls carry that access token in the Authorization: Bearer header.

This is entirely automated by client libraries. You rarely write the signing code yourself. But understanding the flow matters because it reveals where things can go wrong — expired tokens, incorrect audiences, and JWT validation failures are the most common runtime errors.

The Role of Application Default Credentials

Google Cloud SDK provides Application Default Credentials (ADC), a fallback chain that resolves credentials automatically. When your code calls google.auth.default(), the SDK checks:

1. GOOGLE_APPLICATION_CREDENTIALS environment variable.
2. User-level credentials from gcloud auth application-default login.
3. Workload Identity metadata server (on GCE/GKE/Cloud Run).

ADC is the preferred path. Manually loading credentials.json bypasses ADC and removes the safety net of implicit metadata-server delegation. Only use an explicit credentials file when you cannot rely on the platform's native identity system.

Security Risks and Drawbacks of Service Account Keys

Key Risk #1: Over-Provisioned Service Accounts

Many organizations create service accounts with broad roles like roles/owner or roles/editor because they want the deployment pipeline to "just work." This means a leaked credentials.json exposes every resource in the project. Even worse, rotated keys with broad permissions compound the blast radius.

Best practice: Apply least privilege. Define IAM roles per workload — storage only, compute only, CI/CD only. Google's custom roles feature exists for exactly this purpose.

Key Risk #2: Credential Leakage in Source Control

Accidental commits of credentials.json are among the most common security incidents in cloud-native teams. The file may appear in Docker images, local dev configs, Terraform state, or CI secrets files. Once a key is in public view, rotation alone does not solve the problem — the old key must also be deleted.

Best practice: Scan repositories with gcloud iam service-accounts list audits, use pre-commit hooks, and leverage secret-scanning tools from GitHub, GitLab, and third-party vendors. Delete any leaked key immediately and audit access logs.

Key Risk #3: Long-Lived Keys Without Rotation

Service account keys never expire by default. A key created in 2022 still works in 2026 unless manually disabled. Long-lived keys dramatically increase the window of exposure. Each additional key on a service account multiplies the attack surface.