Key Takeaways

• credentials.json is the service account key file issued by Google Cloud when you create a service account — it contains the private key needed for OAuth 2.0 authentication.
• It grants programmatic access to Google APIs (Cloud Storage, BigQuery, Sheets, etc.) without a human user login.
• Never commit credentials.json to version control; always add it to .gitignore and use environment variables or secret managers in production.
• The file is a standard JSON object with fields: type, project_id, private_key_id, private_key, client_email, and client_id.
• Google recommends rotating service account keys every 90 days and deleting unused ones.
• Common errors like "invalid_grant" or "403 Forbidden" are usually caused by expired keys, missing API enablement, or insufficient IAM roles.

What Is credentials.json in Google Cloud?

Why do I need a credentials.json file?

When you build an application that calls Google APIs (Google Cloud Storage, Gmail, Sheets, BigQuery, or any GCP service), Google must verify who you are and what you're allowed to do. For server-to-server or background-service authentication, Google uses service accounts — not human Google accounts. The credentials.json file is the tangible key pair that proves your service's identity. Without it, API requests return 401 Unauthorized.

What does the credentials.json file contain?

A standard Google service account key file looks like this:

{
  "type": "service_account",
  "project_id": "my-project-id",
  "private_key_id": "abc123keyid",
  "private_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEpA...",
  "client_email": "my-sa@my-project.iam.gserviceaccount.com",
  "client_id": "123456789",
  "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/..."
}

Each field serves a purpose: type tells the library which auth flow to use, private_key signs JWT tokens, client_email identifies the service account, and the URIs point to Google's OAuth and certificate endpoints.

How to Create a credentials.json File

Step-by-step: creating a service account key

1. Open the Google Cloud Console and select your project.
2. Navigate to IAM & Admin → Service Accounts.
3. Click + Create Service Account, give it a name and ID, then assign a role (e.g., Service Account User, Storage Object Admin, or the principle of least privilege role your app actually needs).
4. After creation, go back to the service account detail page and click Keys → Add Key → Create new key.
5. Choose JSON as the key type and click Create.
6. Download the file immediately — Google will never show the private key again.

Important: Save the downloaded file securely (encrypted storage, secret manager). Once deleted, the key cannot be recovered.

How to Use credentials.json in Your Application

Loading credentials in Python (google-auth)

from google.oauth2 import service_account
from googleapiclient.discovery import build

credentials = service_account.Credentials.from_service_account_file(
    "credentials.json",
    scopes=["https://www.googleapis.com/auth/spreadsheets.readonly"]
)

service = build("sheets", "v4", credentials=credentials)
results = service.spreadsheets().values().get(
    spreadsheetId="YOUR_SHEET_ID", range="Sheet1!A1:D5"
).execute()

Loading credentials in Node.js

const {GoogleAuth} = require("google-auth-library");
const auth = new GoogleAuth({
  keyFile: "./credentials.json",
  scopes: ["https://www.googleapis.com/auth/cloud-platform"],
});
const client = await auth.getClient();
const accessToken = await client.getAccessToken();

Loading credentials in Go

ctx := context.Background()
creds, err := google.DefaultCredentials(ctx, "https://www.googleapis.com/auth/cloud-platform")
if err != nil { ... }
client := oauth2.NewClient(ctx, creds.TokenSource)

Using credentials.json with gcloud CLI

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/credentials.json"
gcloud auth activate-service-account --key-file=$GOOGLE_APPLICATION_CREDENTIALS

Most Google client libraries automatically detect the GOOGLE_APPLICATION_CREDENTIALS environment variable, so explicitly passing the file path is often unnecessary.

Security Best Practices for credentials.json

How do I keep my credentials.json safe?

• Never commit to Git. Add credentials.json to your .gitignore immediately.
• Use a secrets manager. Google Secret Manager, AWS Secrets Manager, or HashiCorp Vault should hold the file in production, not the filesystem.
• Restrict IAM roles. Assign only the minimum permissions your service needs (principle of least privilege).
• Rotate keys regularly. Set a 90-day rotation schedule. Create a new key, update your application, then delete the old one.
• Disable unused keys. If a key has been rotated out, disable it before deletion to catch any running services still using it.
• Encrypt at rest. Store the file on encrypted disks (GCE machine type with Confidential Computing, or encrypted S3/GCS buckets).
• Monitor access logs. Enable Cloud Audit Logs and set alerts for unexpected API usage from the service account.

Service Account vs. User OAuth vs. Workload Identity

Which authentication method is right for my use case?