Authentication methods

Prism Vertex supports two authentication methods: service account credentials and API keys. Choose the method that best fits your deployment environment.

Authentication methods overview

Service account

Recommended for production. Uses Google Cloud service account JSON credentials with automatic Bearer token generation.

API key

Simple authentication with an API key. Works in both Standard and Express modes.

Service account authentication

Service account authentication uses a Google Cloud service account JSON key file. The provider automatically obtains Bearer tokens using the google/auth library.

Setup

Create a service account

Create a service account in your Google Cloud project with Vertex AI permissions.

Download the JSON key

Download the service account JSON key file from the Google Cloud Console.

Store the file securely

Place the JSON file in a secure location outside your project root. Never commit it to version control.

Configure the path

Set the credentials option to the absolute path of your JSON file.

Configuration

'vertex' => [
    'project_id'  => env('VERTEX_PROJECT_ID'),
    'location'    => env('VERTEX_LOCATION', 'us-central1'),
    'credentials' => env('VERTEX_CREDENTIALS'),
],

Set the path in your .env file:

VERTEX_CREDENTIALS=/var/secrets/vertex-service-account.json

Always store service account files outside your web root and never commit them to version control. Use environment variables or secret management systems.

How it works

The provider uses the resolveAccessToken() method to obtain a Bearer token:

protected function resolveAccessToken(): string
{
    if (! class_exists(ServiceAccountCredentials::class)) {
        throw new PrismException(
            'The google/auth package is required for service account authentication. Install it with: composer require google/auth'
        );
    }

    $path = $this->credentials ?? '';

    if (! is_file($path)) {
        throw new PrismException(
            "Vertex AI credentials file not found: {$path}"
        );
    }

    $credentials = new ServiceAccountCredentials(
        scope: 'https://www.googleapis.com/auth/cloud-platform',
        jsonKey: json_decode((string) file_get_contents($path), true),
    );

    $token = $credentials->fetchAuthToken();

    return $token['access_token'];
}

Requirements

The google/auth package must be installed:
```
composer require google/auth
```
The service account must have the Vertex AI User role or equivalent permissions
The JSON key file must be readable by your application

Service account permissions

Your service account needs these IAM roles:

roles/aiplatform.user - Vertex AI User (minimum required)
roles/aiplatform.admin - Vertex AI Administrator (if you need full access)

Error handling

Common errors with service account authentication:

Package not installed
File not found
Invalid permissions

Error:

The google/auth package is required for service account authentication.
Install it with: composer require google/auth

Solution:

composer require google/auth

Error:

Vertex AI credentials file not found: /path/to/service-account.json

Solution: Verify the path in your .env file points to the correct location and the file exists.

Error:

403 Forbidden - The caller does not have permission

Solution: Grant your service account the Vertex AI User role in the Google Cloud Console.

API key authentication

API key authentication is simpler but less secure. The API key is sent as a query parameter on every request.

Configuration

Standard mode
Express mode

'vertex' => [
    'project_id' => env('VERTEX_PROJECT_ID'),
    'location'   => env('VERTEX_LOCATION', 'us-central1'),
    'api_key'    => env('VERTEX_API_KEY'),
],

'vertex' => [
    'api_key' => env('VERTEX_API_KEY'),
    // project_id and location omitted — triggers Express mode
],

Set the API key in your .env file:

VERTEX_API_KEY=your-api-key-here

How it works

The API key is added as a query parameter to every request:

if ($this->apiKey !== null && $this->apiKey !== '') {
    $client = $client->withQueryParameters(['key' => $this->apiKey]);
}

Requests are sent with the key in the URL:

https://aiplatform.googleapis.com/v1/publishers/google/models/gemini-2.5-flash:generateContent?key=your-api-key

When to use API keys

Development

Quick setup for local development and testing.

Express mode

Required for Vertex AI Express mode configuration.

Simple apps

Small applications that don’t need complex authentication.

Prototyping

Fast prototyping without setting up service accounts.

Security considerations

API keys are less secure than service accounts because they:

Are included in request URLs (may be logged)
Cannot be rotated automatically
Have broader permissions
Don’t support fine-grained access control

Use service accounts for production environments.

Choosing an authentication method

Production
Development
Express mode

Use service accounts:

Better security with automatic token rotation
Fine-grained IAM permissions
Audit trail in Google Cloud
No risk of key exposure in URLs

'vertex' => [
    'project_id'  => env('VERTEX_PROJECT_ID'),
    'location'    => env('VERTEX_LOCATION', 'us-central1'),
    'credentials' => env('VERTEX_CREDENTIALS'),
],

Use API keys:

Simple setup without JSON files
Works immediately after generation
No need for google/auth package
Easy to share across team (via .env.example)

'vertex' => [
    'project_id' => env('VERTEX_PROJECT_ID'),
    'location'   => env('VERTEX_LOCATION', 'us-central1'),
    'api_key'    => env('VERTEX_API_KEY'),
],

Only API keys supported:

Service accounts don’t work with Express mode
No project or location required
Simplest possible setup

'vertex' => [
    'api_key' => env('VERTEX_API_KEY'),
],

Combining both methods

You cannot use both credentials and api_key simultaneously. The provider prioritizes service account credentials:

if ($this->credentials !== null && $this->credentials !== '') {
    return $client->withToken($this->resolveAccessToken());
}

if ($this->apiKey !== null && $this->apiKey !== '') {
    $client = $client->withQueryParameters(['key' => $this->apiKey]);
}

If you set both options, only the service account credentials will be used.

Per-environment configuration

Use different authentication methods per environment:

'vertex' => [
    'project_id'  => env('VERTEX_PROJECT_ID'),
    'location'    => env('VERTEX_LOCATION', 'us-central1'),
    'credentials' => env('VERTEX_CREDENTIALS'), // production
    'api_key'     => env('VERTEX_API_KEY'),     // development (fallback)
],

In production .env:

VERTEX_CREDENTIALS=/var/secrets/vertex-service-account.json

In local .env:

VERTEX_API_KEY=your-development-api-key

Get Started

Configuration

Core Features

Providers

Advanced