Set up a Vertex AI Express provider

Configure a Vertex AI Express provider in Aperture so your team can access Google Gemini models through your tailnet. Vertex AI Express uses API key authentication instead of a service account, which simplifies setup when you need Gemini models without Anthropic support.

If you also need Anthropic Claude models through Vertex AI, use a service account provider instead. The Vertex AI raw predict endpoint required by Anthropic models does not support API key authentication.

Prerequisites

Before you begin, you need:

• An Aperture instance accessible from your device. Refer to get started with Aperture if you have not set this up.
• A Google Cloud project with the Vertex AI API enabled.
• Your Aperture hostname (Tailscale's MagicDNS provides short hostnames like ai in your tailnet; for example, aperture.example.ts.net).

Step 1: Create an API key

Create a Google Cloud API key for your project using the Google Cloud console or the gcloud CLI.

Google Cloud console

Follow these steps to create an API key from the console:

1. Open the API credentials page for your project.
2. Select Create credentials, then API key.
3. Copy the generated key.

gcloud CLI

Run the following command to create an API key:

gcloud services api-keys create --display-name="Aperture Vertex AI Express"

The command outputs the key string. Copy it for the next step.

(Optional) Restrict the API key to the Vertex AI API. An unrestricted key works but has a broader scope than necessary.

Step 2: Configure the provider

Add a Vertex provider to your Aperture configuration using the Aperture dashboard. Set the authorization type to x-goog-api-key and provide your API key directly (no keyfile:: prefix).

The following example shows a Vertex Express provider configuration:

{
  "providers": {
    "vertex-express": {
      "baseurl": "https://aiplatform.googleapis.com",
      "authorization": "x-goog-api-key",
      "apikey": "<your-api-key>",
      "models": [
        "gemini-2.5-flash",
        "gemini-2.5-pro",
        "gemini-2.5-flash-lite"
      ],
      "compatibility": {
        "google_generate_content": true
      }
    }
  }
}

Replace <your-api-key> with the API key from the previous step.

The compatibility section enables google_generate_content, which routes requests through the Vertex AI generateContent endpoint used by Google-published models such as Gemini.

Do not enable google_raw_predict. Third-party models (such as Anthropic Claude) use the raw predict endpoint, which requires service account authentication. API key authentication does not support this endpoint.

After configuring the provider, grant model access to the users or groups that need the Gemini models.

Verify the provider

After configuring the provider, confirm it works:

1. Open the Aperture dashboard and confirm the Vertex Express provider appears with the expected models.
2. Send a test request through a connected tool, such as a Gemini CLI instance or another tool pointed at the Vertex AI endpoint.
3. Check the Aperture dashboard session list for a new entry corresponding to your request. The session shows the model name, token counts, and timestamp.

If the request fails, check that the API key is correct and that the Vertex AI API is enabled in your Google Cloud project. For additional help, refer to the Aperture troubleshooting guide.

Limitations compared to service account providers

Vertex AI Express mode requires less configuration but has fewer features than a service account provider:

• Google models only. Anthropic Claude models on Vertex AI use the raw predict endpoint, which requires service account authentication. Express mode does not support google_raw_predict.
• Gemini CLI works, but without experimental_gemini_cli_vertex_compat. Gemini CLI works with Express mode through the standard OpenAI-compatible endpoint. However, the experimental_gemini_cli_vertex_compat flag requires a keyfile-based provider to extract the project ID, so Express mode providers cannot use it. If you need Gemini CLI to use the Vertex-specific endpoint, use a service account provider instead.
• No automatic project ID. Clients that rely on Aperture to fill in the Vertex project ID from the keyfile (the _aperture_auto_vertex_project_id_ placeholder) must instead provide the project ID directly in the request path.

Rotate the API key

To rotate the API key, create a new key, update the Aperture provider configuration, then delete the old key.

1. Create a new API key using the steps in Step 1.

2. Update the apikey field in your Aperture provider configuration with the new key.

3. Delete the old API key from the API credentials page or with the gcloud CLI:

   gcloud services api-keys delete <old-key-id>
   

Requests that use the deleted key fail immediately after you delete it.