[AI Gateway] Clarify Vertex AI authentication and BYOK usage by superhighfives · Pull Request #28600 · cloudflare/cloudflare-docs

superhighfives · 2026-02-25T19:02:32Z

Summary

Addresses customer feedback from Ploy.ai about confusion when setting up AI Gateway with Google Vertex AI.

Changes

BYOK as recommended option: Added clear step-by-step instructions for storing service account credentials via the dashboard, including the region dropdown
Region configuration clarity: Clarified that when using BYOK, the region is selected in the UI dropdown (no need to manually edit the JSON). The region key in JSON is only needed when passing credentials directly in the Authorization header
Authentication headers: Added cf-aig-authorization header to all examples for consistency with other provider docs
Global endpoint warning: Added a note recommending specific regional endpoints (like us-central1) instead of global, which has limited model support
Troubleshooting section: Added guidance for resolving 401 UNAUTHENTICATED errors

Customer Feedback Summary

Docs said to manually add region key to service account JSON, but UI now has a region dropdown - unclear which to use
Using locations/global endpoint resulted in 401 errors
BYOK + Vertex AI flow wasn't clearly documented
Examples were missing cf-aig-authorization header

Testing

npm run check passes (pre-existing unrelated error)
No MDX syntax issues
All code blocks have valid language identifiers

- Add BYOK as recommended option with clear dashboard instructions - Clarify that region dropdown in UI eliminates need for manual JSON editing - Add cf-aig-authorization header to all examples for consistency - Add note about global endpoint limitations (recommend specific regions) - Add troubleshooting section for 401 UNAUTHENTICATED errors - Reorganize authentication options for clarity Addresses customer feedback about region configuration confusion and authentication errors when using AI Gateway with Google Vertex AI.

- Add comparison table showing headers needed for each auth method - Add caution callout about cf-aig-authorization vs Authorization headers - Expand troubleshooting to cover alias checking and URL path verification - Show explicit base64 encoding in non-BYOK examples - Replace ambiguous placeholders with concrete code examples

Copilot

Pull request overview

This PR enhances the Google Vertex AI documentation in response to customer feedback from Ploy.ai about confusion when setting up AI Gateway with Vertex AI. The changes clarify authentication methods, emphasize BYOK as the recommended approach, and add troubleshooting guidance.

Changes:

Restructured authentication documentation to recommend BYOK (Bring Your Own Keys) as Option 1, with clear step-by-step instructions
Clarified region configuration: when using BYOK, region is selected via UI dropdown; when passing credentials in headers, the region key must be added to the JSON
Added cf-aig-authorization header to all code examples for consistency with other provider documentation
Added warning about using specific regional endpoints instead of global endpoint
Added troubleshooting section for 401 UNAUTHENTICATED errors

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

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

Use template literal with lowercase placeholder to match other provider docs.

corywilkerson

Added small comment

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

Explicitly state that users do not need to manually add a region field to their service account JSON when using the dashboard - AI Gateway handles this automatically based on the dropdown selection.

Copilot

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 6 comments.

Comments suppressed due to low confidence (1)

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

The Vertex AI generateContent REST API expects contents to be an array of content objects (for example, "contents": [{...}]). This example uses "contents": { ... }, which will fail if copied verbatim; update the request body to use an array.

    -d '{
        "contents": {
          "role": "user",
          "parts": [
            {
              "text": "Tell me more about Cloudflare"
            }
          ]
        }
      }'

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

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

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

The Vertex AI generateContent API expects 'contents' to be an array, not a single object. Fixed examples that incorrectly used object format.

Copilot

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 2 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

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

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Use google-vertex-ai/google/gemini-2.5-flash to match other unified endpoint examples which include the /google/ publisher prefix.

Copilot

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

Copilot

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

superhighfives · 2026-02-25T22:39:32Z

Great, this should be good for review! 👍

zeke

Not an expert, but looks good at a cursory glance. 👍🏼

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

Move generic troubleshooting content to a dedicated page at /ai-gateway/reference/troubleshooting/. Keep provider-specific content on Vertex and DLP pages with cross-links.

superhighfives · 2026-03-06T18:05:55Z

Great, made those updates. cc @ethulia. 👍

ethulia · 2026-03-06T19:59:22Z

src/content/docs/ai-gateway/reference/troubleshooting.mdx

+
+For provider-specific authentication issues:
+
+- [Google Vertex AI troubleshooting](/ai-gateway/usage/providers/vertex/#troubleshooting)


this link to the vertex page troubleshooting section which then links back here.

I don't mind them linking between one another, but maybe I can phrase it differently?

On Vertex, it has:

For general AI Gateway troubleshooting, refer to Troubleshooting.

On troubleshooting, it has:

For provider-specific authentication issues:

Google Vertex AI troubleshooting

Just following up on this one, @ethulia.

@superhighfives sorry this was my bad, didn't realize there was more to the troubleshooting sections on these pages. will approve.

Copilot AI review requested due to automatic review settings February 25, 2026 19:02

superhighfives requested review from a team, abhishekkankani, kathayl, mchenco, palashgo, roerohan and thebongy as code owners February 25, 2026 19:02

github-actions bot added product:ai-gateway AI Gateway: https://developers.cloudflare.com/ai-gateway/ size/m labels Feb 25, 2026

github-actions bot assigned abhishekkankani, bfirsh, kathayl, mchenco, palashgo, roerohan, thebongy and zeke Feb 25, 2026

Copilot started reviewing on behalf of superhighfives February 25, 2026 19:03 View session

Copilot AI reviewed Feb 25, 2026

View reviewed changes

src/content/docs/ai-gateway/usage/providers/vertex.mdx Outdated Show resolved Hide resolved

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

[AI Gateway] Fix placeholder format in JS example for consistency

54c281c

Use template literal with lowercase placeholder to match other provider docs.

corywilkerson reviewed Feb 25, 2026

View reviewed changes

src/content/docs/ai-gateway/usage/providers/vertex.mdx Outdated Show resolved Hide resolved

[AI Gateway] Clarify that BYOK dashboard auto-applies region

eef1dd1

Explicitly state that users do not need to manually add a region field to their service account JSON when using the dashboard - AI Gateway handles this automatically based on the dropdown selection.

superhighfives requested a review from Copilot February 25, 2026 19:31

Copilot started reviewing on behalf of superhighfives February 25, 2026 19:32 View session

Copilot AI reviewed Feb 25, 2026

View reviewed changes

superhighfives and others added 2 commits February 25, 2026 11:39

Update Vertex AI contents to use an array

a042076

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update base64 suggestion

aa16c68

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

superhighfives and others added 4 commits February 25, 2026 11:41

Use contents array

4cd5901

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Avoid newlines for base64

0513f48

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Make configuration clearer

5570ce0

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

[AI Gateway] Fix Vertex AI request body format

1dd16f6

The Vertex AI generateContent API expects 'contents' to be an array, not a single object. Fixed examples that incorrectly used object format.

superhighfives requested review from Copilot and corywilkerson February 25, 2026 19:46

Copilot started reviewing on behalf of superhighfives February 25, 2026 19:47 View session

Copilot AI reviewed Feb 25, 2026

View reviewed changes

src/content/docs/ai-gateway/usage/providers/vertex.mdx Outdated Show resolved Hide resolved

src/content/docs/ai-gateway/usage/providers/vertex.mdx Outdated Show resolved Hide resolved

superhighfives and others added 2 commits February 25, 2026 11:52

Consistent bash

6c3be94

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

[AI Gateway] Fix model name format in troubleshooting example

002246b

Use google-vertex-ai/google/gemini-2.5-flash to match other unified endpoint examples which include the /google/ publisher prefix.

superhighfives requested a review from Copilot February 25, 2026 19:56

Copilot AI reviewed Feb 25, 2026

View reviewed changes

superhighfives requested a review from Copilot February 25, 2026 21:56

Copilot started reviewing on behalf of superhighfives February 25, 2026 21:57 View session

Copilot AI reviewed Feb 25, 2026

View reviewed changes

zeke approved these changes Feb 26, 2026

View reviewed changes

kodster28 reviewed Feb 26, 2026

View reviewed changes

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

[AI Gateway] Add central troubleshooting page

ed2dd81

Move generic troubleshooting content to a dedicated page at /ai-gateway/reference/troubleshooting/. Keep provider-specific content on Vertex and DLP pages with cross-links.

superhighfives force-pushed the docs/ai-gateway-vertex-auth-clarification branch from a1d9d0f to ed2dd81 Compare March 5, 2026 16:57

ethulia reviewed Mar 6, 2026

View reviewed changes

ethulia requested review from ethulia and kodster28 March 10, 2026 21:34

ethulia approved these changes Mar 10, 2026

View reviewed changes


		For provider-specific authentication issues:

		- [Google Vertex AI troubleshooting](/ai-gateway/usage/providers/vertex/#troubleshooting)

Conversation

superhighfives commented Feb 25, 2026

Summary

Changes

Customer Feedback Summary

Testing

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

corywilkerson left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

superhighfives commented Feb 25, 2026

Uh oh!

zeke left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

superhighfives commented Mar 6, 2026

Uh oh!

ethulia Mar 6, 2026

Choose a reason for hiding this comment

Uh oh!

superhighfives Mar 6, 2026

Choose a reason for hiding this comment

Uh oh!

superhighfives Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

ethulia Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

13 participants