Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
googleAutoAuth
✓ const googleAutoAuth = require('google-auto-auth');
✗ import googleAutoAuth from 'google-auto-auth';
This library is primarily CommonJS (`require`). While ESM interop might work in some bundlers, `require` is the intended and most reliable import mechanism.
AuthClient
✓ const authClient = googleAutoAuth(authConfig);
✗ const authClient = new googleAutoAuth(authConfig);
Since v0.7.0, the `new` keyword is explicitly forbidden for instantiating the client. The function should be invoked directly. Using `new` will result in a runtime error.
authorizeRequest
✓ authClient.authorizeRequest(reqOpts, callback);
✗ googleAutoAuth.authorizeRequest(reqOpts, callback);
The `authorizeRequest` method is available on the *instance* returned by `googleAutoAuth()`, not on the module itself.
This quickstart demonstrates how to initialize `google-auto-auth`, authorize an example API request, directly retrieve an access token, and access the underlying `google-auth-library` client. It highlights credential auto-discovery and explicit configuration.
const googleAutoAuth = require('google-auto-auth');
const path = require('path');
// IMPORTANT: In a real application, never hardcode credentials or paths directly.
// Use environment variables or a secure configuration management system.
// For demonstration, we'll simulate a key file path.
process.env.GOOGLE_APPLICATION_CREDENTIALS = process.env.GOOGLE_APPLICATION_CREDENTIALS ?? path.join(__dirname, 'mock-key.json');
// If GOOGLE_APPLICATION_CREDENTIALS is not set or not valid, you must provide authConfig.
// Example with explicit credentials (replace with your actual data):
const authConfig = {
// keyFilename: process.env.GOOGLE_APPLICATION_CREDENTIALS, // Path to a .json, .pem, or .p12 key file
// OR
// credentials: {
// client_email: process.env.GOOGLE_CLIENT_EMAIL ?? 'your-service-account@your-project.iam.gserviceaccount.com',
// private_key: process.env.GOOGLE_PRIVATE_KEY ?? '-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n',
// },
scopes: ['https://www.googleapis.com/auth/cloud-platform'] // Required scopes for your API requests
};
// Create an auth client. It will automatically attempt to find credentials.
// If authConfig is empty and no default credentials are found, it might fail.
const auth = googleAutoAuth(authConfig);
// 1. Authorize an HTTP request object
auth.authorizeRequest({
method: 'GET',
uri: 'https://storage.googleapis.com/storage/v1/b'
}, (err, authorizedReqOpts) => {
if (err) {
console.error('Error authorizing request:', err.message);
// Handle specific errors like MISSING_SCOPE
if (err.code === 'MISSING_SCOPE') {
console.error('Missing required scopes. Please configure `authConfig.scopes`.');
}
return;
}
console.log('Authorized Request Options:', authorizedReqOpts);
// authorizedReqOpts now contains `headers: { Authorization: 'Bearer {{token}}' }`
});
// 2. Get an access token directly
auth.getToken((err, token) => {
if (err) {
console.error('Error getting token:', err.message);
return;
}
console.log('Access Token:', token ? token.substring(0, 20) + '...' : 'No token received');
});
// 3. Get the underlying google-auth-library client
auth.getAuthClient((err, client) => {
if (err) {
console.error('Error getting auth client:', err.message);
return;
}
console.log('Underlying google-auth-library client type:', client.constructor.name);
// You can interact with the google-auth-library client directly here if needed.
});
Errors
Common errors & fixes
TypeError: googleAutoAuth is not a constructor
Attempting to use the `new` keyword to instantiate the `google-auto-auth` client after v0.7.0.
fixRemove the `new` keyword. Instead of `new googleAutoAuth()`, use `googleAutoAuth()`.
Error: Could not load the default credentials. Browse to https://cloud.google.com/docs/authentication/getting-started to authenticate.
The library failed to automatically find credentials in the environment (e.g., not on GCP, `gcloud` not authenticated, `GOOGLE_APPLICATION_CREDENTIALS` not set or invalid).
fixEnsure you are running on GCP, logged in via `gcloud auth application-default login`, or set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to a valid service account key file path. Alternatively, provide credentials explicitly in `authConfig`.
Error: MISSING_SCOPE
The API request requires specific OAuth scopes that were not provided in the `authConfig.scopes` array.
fixReview the documentation for the Google API you are calling and add the necessary scope URLs (e.g., `https://www.googleapis.com/auth/cloud-platform`) to the `scopes` array in your `authConfig`.
Audit
Dependencies
google-auth-libraryrequiredThis is the underlying official Google authentication library that `google-auto-auth` uses to perform the actual credential management and token acquisition.