@gpc-cli/auth

Authentication for the Google Play Developer API. Part of GPC.

Service account, OAuth, and Application Default Credentials — with automatic token caching and a simple AuthClient interface. Works with your existing Google Play service account; no new credentials or extra permissions needed.

Install

npm install @gpc-cli/auth

Quick Start

import { resolveAuth } from "@gpc-cli/auth";
import { createApiClient } from "@gpc-cli/api";

const auth = await resolveAuth({
  serviceAccountPath: "./service-account.json",
});

const client = createApiClient({ auth });

Authentication Methods

Service Account (file path)

The most common method for CI/CD and automation. Download a service account JSON key from the Google Cloud Console.

import { resolveAuth } from "@gpc-cli/auth";

const auth = await resolveAuth({
  serviceAccountPath: "./service-account.json",
});

Service Account (JSON string)

Pass the key contents directly. Useful for environment variables and secrets managers.

import { resolveAuth } from "@gpc-cli/auth";

const auth = await resolveAuth({
  serviceAccountJson: process.env.SERVICE_ACCOUNT_KEY,
});

Service Account (manual creation)

For more control, load and create the auth client in two steps:

import { loadServiceAccountKey, createServiceAccountAuth } from "@gpc-cli/auth";

const key = await loadServiceAccountKey("./service-account.json");
const auth = createServiceAccountAuth(key);

console.log(auth.getClientEmail()); // your-sa@project.iam.gserviceaccount.com
console.log(auth.getProjectId()); // your-gcp-project-id

loadServiceAccountKey accepts a file path or a raw JSON string, and validates the key structure before returning.

Application Default Credentials

Works automatically in GCP-hosted environments (Cloud Build, Cloud Run, GKE) and locally after running gcloud auth application-default login.

import { resolveAuth } from "@gpc-cli/auth";

// No options needed -- resolveAuth falls back to ADC automatically
const auth = await resolveAuth();

Environment Variables

resolveAuth checks these environment variables when no explicit options are provided:

Resolution Order

resolveAuth tries credentials in this order:

1. serviceAccountJson option (inline JSON)
2. serviceAccountPath option (file path)
3. GPC_SERVICE_ACCOUNT environment variable
4. GOOGLE_APPLICATION_CREDENTIALS environment variable
5. Application Default Credentials

The first method that succeeds is used.

Token Caching

Access tokens are cached in memory and reused until they expire. This avoids redundant token requests when making multiple API calls.

To clear the cache manually:

import { clearTokenCache } from "@gpc-cli/auth";

clearTokenCache();

AuthClient Interface

Every auth method returns an AuthClient:

interface AuthClient {
  getAccessToken(): Promise<string>;
  getProjectId(): string | undefined;
  getClientEmail(): string;
}

This is the interface that @gpc-cli/api expects. You can also implement it yourself for custom auth flows:

import { createApiClient } from "@gpc-cli/api";

const client = createApiClient({
  auth: {
    async getAccessToken() {
      return fetchTokenFromVault();
    },
    getProjectId() {
      return "my-project";
    },
    getClientEmail() {
      return "custom@example.com";
    },
  },
});

Type Exports

import type { AuthOptions, AuthClient, ServiceAccountKey } from "@gpc-cli/auth";

Error Handling

Auth failures throw AuthError with a code and actionable suggestion:

import { AuthError } from "@gpc-cli/auth";

try {
  const auth = await resolveAuth();
} catch (error) {
  if (error instanceof AuthError) {
    console.error(error.code); // e.g. "AUTH_NO_CREDENTIALS"
    console.error(error.suggestion); // step-by-step fix
    console.error(error.toJSON()); // structured error object
  }
}

Error codes:

Documentation

• Full documentation
• SDK usage guide

Licensing

Free to use. Source code is on GitHub at yasserstudio/gpc.