google credentialsjson

What Is a Google credentials.json File?

A credentials.json file is a JSON-formatted service account key issued by Google Identity. It proves your application's identity when calling Google APIs — from Cloud Storage and BigQuery to Google Sheets and Gmail. Unlike an OAuth consent-screen flow that redirects a human user through a browser, a service account key enables server-to-server authentication, making it the backbone of automated pipelines, CI/CD deployments, and background workers.

The file typically looks like this:

{
  "type": "service_account",
  "project_id": "my-project-12345",
  "private_key_id": "a1b2c3d4...",
  "private_key": "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBg...\n-----END PRIVATE KEY-----\n",
  "client_email": "my-sa@my-project-12345.iam.gserviceaccount.com",
  "client_id": "112233445566778899",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token"
}

Each field maps to a specific purpose in the OAuth 2.0 client-credentials grant flow that your SDK uses under the hood.

How to Generate a credentials.json File

Step-by-Step through Google Cloud Console

1. Navigate to Google Cloud Console → IAM & Admin → Service Accounts.
2. Click + Create Service Account, assign a name and description.
3. Grant the role(s) your application needs (e.g., Cloud Storage Object Admin, BigQuery Data Editor). Choose roles deliberately — principle of least privilege reduces blast radius if the key leaks.
4. Under Fine-tune access, add any additional roles required by your workload.
5. On the Service Account Keys screen, click Add Key → Create new key.
6. Select JSON as the key type and click Create.
7. Download the file immediately. Google stores only the public key; the private key is delivered once and cannot be retrieved again.

Step-by-Step through the gcloud CLI

gcloud iam service-accounts create my-sa \
  --display-name "My Service Account" \
  --project my-project-12345

gcloud iam service-accounts keys create credentials.json \
  --iam-account my-sa@my-project-12345.iam.gserviceaccount.com

The CLI approach is ideal for automation scripts and Infrastructure-as-Code pipelines.

Where Do You Use credentials.json?

Security Best Practices for credentials.json

Checklist

• Never hard-code the path or contents of credentials.json in source files.
• Add the filename to .gitignore and audit history with tools like git-secrets or truffleHog.
• Use environment variables or a secrets manager (e.g., Google Secret Manager, AWS Secrets Manager) to inject the path at runtime.
• Rotate keys periodically — create a new key, update your application, then delete the old one.
• Enable audit logging on the service account to detect unusual API calls.
• Restrict key usage with Cloud Asset Inventory and Identity-Aware Proxy where possible.
• Prefer Application Default Credentials (ADC) when running inside Google Cloud — the metadata server supplies tokens automatically with no file to manage.
• Delete unused keys — each extra key increases your attack surface.

Troubleshooting credentials.json Errors

Common Error Codes and Fixes