How to Authenticate to Agent Platform GenAI Using Google Cloud Credentials

Authenticate to Agent Platform GenAI by obtaining an OAuth 2.0 Bearer token through Application Default Credentials (ADC), service account keys, or Workload Identity, then present it in the Authorization: Bearer <TOKEN> header for REST calls or pass it to the client SDK constructor.

The Gemini Enterprise Agent Platform (GenAI) is a Google Cloud-managed service that requires OAuth 2.0 authentication for all API requests. According to the google/skills repository, the platform validates credentials by inspecting the token's subject claim against Cloud IAM policies attached to the calling principal. This guide explains how to authenticate to Agent Platform GenAI using Google Cloud credentials for interactive development, automated pipelines, and GKE workloads.

Understanding the Authentication Architecture

The Agent Platform relies on Cloud IAM to authorize principals (users or service accounts) who present valid OAuth 2.0 Bearer tokens. As documented in skills/cloud/agent-platform-troubleshooting/references/policies.md, the platform maps the token's sub claim to IAM principals using principal:// URIs.

Application Default Credentials (ADC) provides the unified interface for obtaining these tokens. When you use ADC, the client libraries automatically fetch short-lived access tokens from the metadata server (on GCE/GKE) or from local credential files without embedding keys in your code.

For GKE deployments, Workload Identity allows Kubernetes service accounts to impersonate Google Cloud service accounts. This eliminates the need to manage JSON key files and is the recommended production approach.

Step-by-Step Authentication Setup

Enable Required APIs and Grant IAM Roles

Enable the Vertex AI and Agent Platform APIs in your Google Cloud project:

gcloud services enable aiplatform.googleapis.com
gcloud services enable genai.googleapis.com

Grant the roles/aiplatform.user role to the identity that will call the API. For service accounts, use:

gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member="serviceAccount:$SA_EMAIL" \
    --role="roles/aiplatform.user"

Configure Your Credentials

Choose one of three authentication methods based on your deployment target.

Interactive Development (User Account)

Run the command documented in skills/cloud/gcloud/SKILL.md to store credentials in ~/.config/gcloud:

gcloud auth application-default login

CI/CD or Local Development (Service Account Key)

Export the path to a service account JSON key:

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/sa-key.json

GKE Production (Workload Identity)

Annotate your Kubernetes service account to bind it to a Cloud IAM service account:

metadata:
  annotations:
    iam.gke.io/gcp-service-account: my-sa@my-project.iam.gserviceaccount.com

Obtain and Use Access Tokens

For REST API calls, generate a token using gcloud. This token is automatically scoped for https://www.googleapis.com/auth/cloud-platform:

ACCESS_TOKEN=$(gcloud auth print-access-token)

Call the Agent Platform endpoint using cURL as shown in skills/cloud/gemini-api/SKILL.md:

curl -X POST "https://$LOCATION-aiplatform.googleapis.com/v1beta1/projects/$PROJECT_ID/locations/$LOCATION/publishers/google/models/$MODEL:generateContent" \
     -H "Authorization: Bearer $ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"contents":[{"role":"user","parts":[{"text":"Write a haiku about clouds."}]}]}'

Implement Authentication in Client Libraries

Using Python with the GenAI SDK:

import google.auth
from google.generativeai import GenerativeModel

# ADC automatically picks up the credentials

credentials, project_id = google.auth.default()
model = GenerativeModel("gemini-1.5-flash", credentials=credentials)
response = model.generate_content("Write a haiku about clouds.")
print(response.text)

Using Java:

import com.google.auth.oauth2.GoogleCredentials;
import com.google.cloud.aiplatform.v1beta1.PredictionServiceClient;
import com.google.cloud.aiplatform.v1beta1.PredictionServiceSettings;

GoogleCredentials credentials = GoogleCredentials.getApplicationDefault()
    .createScoped("https://www.googleapis.com/auth/cloud-platform");
PredictionServiceSettings settings = PredictionServiceSettings.newBuilder()
    .setCredentialsProvider(() -> credentials)
    .build();
try (PredictionServiceClient client = PredictionServiceClient.create(settings)) {
    // Make request using client...
}

Troubleshooting Common Authentication Failures

PERMISSION_DENIED Errors

Verify the principal has the required aiplatform.* roles. The skills/cloud/agent-platform-troubleshooting/references/policies.md file explains how the platform evaluates principalSubject fields against IAM policies. You may also need to check skills/cloud/agent-platform-troubleshooting/references/known-issues.md for specific error patterns.

Invalid Token Audiences

Ensure tokens are scoped for https://www.googleapis.com/auth/cloud-platform. The gcloud auth print-access-token command automatically uses this scope, but manually generated tokens may fail if scoped incorrectly.

Workload Identity Misconfiguration

Confirm the GKE node pool has the iam.gke.io/gke-metadata-server enabled and that the Kubernetes service account annotation exactly matches the Cloud service account email address.

Short-Lived Delegated Credentials

For token impersonation scenarios, use:

gcloud iam service-accounts impersonate $SA_EMAIL \
    --credential-source-file=./key.json \
    --format="value(token)"

Summary

• Agent Platform GenAI requires OAuth 2.0 Bearer tokens obtained through Google Cloud IAM.
• Application Default Credentials (ADC) is the recommended method, automatically selecting credentials from the metadata server or GOOGLE_APPLICATION_CREDENTIALS environment variable.
• Service account keys are suitable for non-interactive CI/CD pipelines but should be avoided in production GKE clusters in favor of Workload Identity.
• The platform validates tokens against IAM policies documented in skills/cloud/agent-platform-troubleshooting/references/policies.md.
• Client libraries for Python and Java accept credential objects directly, while REST calls require the Authorization: Bearer <TOKEN> header as specified in skills/cloud/gemini-api/references/client_server_messages.md.

Frequently Asked Questions

What IAM roles are required to access Agent Platform GenAI?

The calling principal must possess a role containing aiplatform.* permissions, typically roles/aiplatform.user for inference operations or roles/aiplatform.admin for management tasks. According to skills/cloud/agent-platform-troubleshooting/references/policies.md, the platform checks these roles against the token's subject claim.

How does Application Default Credentials (ADC) work with Agent Platform?

ADC is a strategy implemented in Google Cloud client libraries that automatically discovers credentials from the environment. As shown in skills/cloud/gemini-api/SKILL.md, when you call google.auth.default(), the library checks for the GOOGLE_APPLICATION_CREDENTIALS environment variable, gcloud's default credentials, or the GCE/GKE metadata server in that order.

Can I use Workload Identity with Agent Platform on GKE?

Yes. Workload Identity is the recommended approach for GKE workloads. By annotating your Kubernetes service account with iam.gke.io/gcp-service-account, you allow pods to obtain tokens for the linked Google Cloud service account without mounting JSON keys. This method is referenced in the authentication model documentation within the google/skills repository.

Why do I receive a PERMISSION_DENIED error despite having valid credentials?

This error typically indicates the authenticated principal lacks the necessary IAM role bindings, or the token has an incorrect audience scope. Verify the principal has roles/aiplatform.user and that the token scope includes https://www.googleapis.com/auth/cloud-platform. The skills/cloud/agent-platform-troubleshooting/references/policies.md file provides detailed guidance on how the platform maps token subjects to IAM principals.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}