[AI Gateway]: Add documentation for service account based auth and unified API on Vertex (#25561)

Co-authored-by: Rishit Bansal <[email protected]>

Author: thebongy

src/content/docs/ai-gateway/usage/providers/vertex.mdx

@@ -43,7 +43,123 @@ Then you can append the endpoint you want to hit, for example: `/publishers/goog
 
 So your final URL will come together as: `https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/google-vertex-ai/v1/projects/{project_name}/locations/{region}/publishers/google/models/gemini-1.0-pro-001:generateContent`
 
-## Example
+## Authenticating with Vertex AI
+
+Authenticating with Vertex AI normally requires generating short-term credentials using the [Google Cloud SDKs](https://cloud.google.com/vertex-ai/docs/authentication) with a complicated setup, but AI Gateway simplifies this for you with multiple options:
+
+### Option 1: Service Account JSON
+
+AI Gateway supports passing a Google service account JSON directly in the `Authorization` header on requests or through AI Gateway's [Bring Your Own Keys](/ai-gateway/configuration/bring-your-own-keys/) feature.
+
+You can [create a service account key](https://cloud.google.com/iam/docs/keys-create-delete) in the Google Cloud Console. Ensure that the service account has the required permissions for the Vertex AI endpoints and models you plan to use.
+
+AI Gateway uses your service account JSON to generate short-term access tokens which are cached and used for consecutive requests, and are automatically refreshed when they expire.
+
+:::note
+The service account JSON must include an additional key called `region` with the GCP region code (for example, `us-east1`) you intend to use for your [Vertex AI endpoint](https://cloud.google.com/vertex-ai/docs/reference/rest#service-endpoint). You can also pass the region code `global` to use the global endpoint.
+:::
+
+#### Example service account JSON structure
+
+```json
+{
+  "type": "service_account",
+  "project_id": "your-project-id",
+  "private_key_id": "your-private-key-id",
+  "private_key": "-----BEGIN PRIVATE KEY-----\nYOUR_PRIVATE_KEY\n-----END PRIVATE KEY-----\n",
+  "client_email": "[email protected]",
+  "client_id": "your-client-id",
+  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
+  "token_uri": "https://oauth2.googleapis.com/token",
+  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
+  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/your-service-account%40your-project.iam.gserviceaccount.com",
+  "region": "us-east1"
+}
+```
+
+You can pass this JSON in the `Authorization` header or configure it in [Bring Your Own Keys](/ai-gateway/configuration/bring-your-own-keys/).
+
+### Option 2: Direct Access Token
+
+If you are already using the Google Cloud SDKs and generating a short-term access token (for example, with `gcloud auth print-access-token`), you can directly pass this as a Bearer token in the `Authorization` header of the request.
+
+:::note
+This option is only supported for the provider-specific endpoint, not for the unified chat completions endpoint.
+:::
+
+```bash
+curl "https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/google-vertex-ai/v1/projects/{project_name}/locations/{region}/publishers/google/models/gemini-1.0-pro-001:generateContent" \
+    -H "Authorization: Bearer ya29.c.b0Aaekm1K..." \
+    -H 'Content-Type: application/json' \
+    -d '{
+        "contents": {
+          "role": "user",
+          "parts": [
+            {
+              "text": "Tell me more about Cloudflare"
+            }
+          ]
+        }
+      }'
+```
+
+## Using Unified Chat Completions API
+
+AI Gateway provides a [Unified API](/ai-gateway/usage/chat-completion/) that works across providers. For Google Vertex AI, you can use the standard chat completions format. Note that the model field includes the provider prefix, so your model string will look like `google-vertex-ai/google/gemini-2.5-pro`.
+
+### Endpoint
+
+```txt
+https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/compat/chat/completions
+```
+
+### Example with OpenAI SDK
+
+```javascript
+import OpenAI from 'openai';
+
+const client = new OpenAI({
+  apiKey: '{service_account_json}',
+  baseURL: 'https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/compat'
+});
+
+const response = await client.chat.completions.create({
+  model: 'google-vertex-ai/google/gemini-2.5-pro',
+  messages: [
+    {
+      role: 'user',
+      content: 'What is Cloudflare?'
+    }
+  ]
+});
+
+console.log(response.choices[0].message.content);
+```
+
+### Example with cURL
+
+```bash
+curl "https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/compat/chat/completions" \
+    -H "Authorization: Bearer {service_account_json}" \
+    -H 'Content-Type: application/json' \
+    -d '{
+        "model": "google-vertex-ai/google/gemini-2.5-pro",
+        "messages": [
+          {
+            "role": "user",
+            "content": "What is Cloudflare?"
+          }
+        ]
+      }'
+```
+
+:::note
+See the [Authenticating with Vertex AI](#authenticating-with-vertex-ai) section below for details on the service account JSON structure and authentication options.
+:::
+
+## Using Provider-Specific Endpoint
+
+You can also use the provider-specific endpoint to access the full Vertex AI API.
 
 ### cURL
 
@@ -62,3 +178,4 @@ curl "https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/google-vert
         }'
 
 ```
+