From 6031b7943559e3a30013029d510baae7c708c395 Mon Sep 17 00:00:00 2001 From: Kenneth Johnson Date: Wed, 1 Jul 2026 11:47:08 -0500 Subject: [PATCH 1/5] [AI Gateway] Document Access user metadata --- .../2026-07-01-access-user-id-metadata.mdx | 13 ++++ .../configuration/custom-domains.mdx | 74 +++++++++++++++++++ .../observability/custom-metadata.mdx | 8 ++ 3 files changed, 95 insertions(+) create mode 100644 src/content/changelog/ai-gateway/2026-07-01-access-user-id-metadata.mdx create mode 100644 src/content/docs/ai-gateway/configuration/custom-domains.mdx diff --git a/src/content/changelog/ai-gateway/2026-07-01-access-user-id-metadata.mdx b/src/content/changelog/ai-gateway/2026-07-01-access-user-id-metadata.mdx new file mode 100644 index 00000000000..0dd547c7c18 --- /dev/null +++ b/src/content/changelog/ai-gateway/2026-07-01-access-user-id-metadata.mdx @@ -0,0 +1,13 @@ +--- +title: Track Access users in AI Gateway metadata +description: AI Gateway now adds the authenticated Access user ID to request metadata for Access-protected custom domain traffic. +products: + - ai-gateway +date: 2026-07-01 +--- + +AI Gateway now records the authenticated Cloudflare Access user ID in request metadata for traffic sent through an Access-protected custom domain. + +When AI Gateway receives a valid Access JWT with a user subject, it adds the user's Access `sub` claim as `cf.user_id`. You can use this metadata field to filter logs, review usage, and build per-user or per-team spend controls without passing user IDs from the client application. + +For setup instructions, refer to [Custom domains](/ai-gateway/configuration/custom-domains/). diff --git a/src/content/docs/ai-gateway/configuration/custom-domains.mdx b/src/content/docs/ai-gateway/configuration/custom-domains.mdx new file mode 100644 index 00000000000..066dfa140e2 --- /dev/null +++ b/src/content/docs/ai-gateway/configuration/custom-domains.mdx @@ -0,0 +1,74 @@ +--- +pcx_content_type: configuration +title: Custom domains +description: Use a custom hostname for AI Gateway and protect it with Cloudflare Access. +sidebar: + order: 8 +products: + - ai-gateway +--- + +Custom domains let you send AI Gateway requests through a hostname that you own, such as `ai.example.com`. You can then protect that hostname with [Cloudflare Access](/cloudflare-one/access-controls/applications/http-apps/) so users authenticate with your identity provider before they can call your gateway. + +When a request to a custom domain includes a valid Cloudflare Access JWT, AI Gateway accepts the Access JWT as the request credential. The client does not need to send an AI Gateway token for that request. AI Gateway also adds the verified Access user ID to request metadata as [`cf.user_id`](/ai-gateway/observability/custom-metadata/#reserved-metadata), so you can filter logs, analytics, and spend by the authenticated user. + +## How it works + +Custom domains use provider-relative paths. The hostname identifies the account and gateway, so the request path starts with the provider route rather than `/v1/{account_id}/{gateway_id}`. + +For example, if your custom domain is `ai.example.com`, an OpenAI-compatible request uses: + +```txt +https://ai.example.com/openai/v1/chat/completions +``` + +Instead of: + +```txt +https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openai/v1/chat/completions +``` + +Before AI Gateway forwards the request to the upstream provider, it removes Cloudflare-only credentials such as the Access JWT and AI Gateway authorization headers. + +## Set up a custom domain + +Custom domains for AI Gateway are being rolled out. If the option is not visible in your account, contact your Cloudflare account team. + +To add a custom domain: + +1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **AI** > **AI Gateway**. +2. Select the gateway you want to configure. +3. Go to **Settings** > **Custom domains**. +4. Add the hostname you want to use for this gateway. +5. Create the DNS record shown in the dashboard. The custom domain remains in a pending state until domain control validation completes. +6. After the custom domain is active, create a [Cloudflare Access self-hosted application](/cloudflare-one/access-controls/applications/http-apps/) for the same hostname. +7. Add Access policies that define which users can call the gateway. + +After setup, users can make requests to the custom domain after authenticating through Access. Requests with a valid Access user subject include `cf.user_id` in AI Gateway metadata. + +## Example request + +After the user authenticates to Access, send requests to the custom domain with the provider-relative path: + +```bash +curl -X POST "https://ai.example.com/openai/v1/chat/completions" \ + --header "Content-Type: application/json" \ + --data '{ + "model": "gpt-4.1-mini", + "messages": [ + { + "role": "user", + "content": "What is Cloudflare?" + } + ] + }' +``` + +If you call the custom domain from a non-browser client, include the Access token using the header or cookie format supported by Cloudflare Access. For example, [`cloudflared access curl`](/cloudflare-one/access-controls/authenticate-agents/#make-requests-with-cloudflared-access-curl) can send the Access token for command-line requests. + +## Limitations + +- Custom-domain routes are provider-relative. Do not include `/v1/{account_id}/{gateway_id}` in the path when using the custom hostname. +- `cf.user_id` is only added when AI Gateway receives a valid Access JWT with a non-empty user subject. +- Service-token requests do not include `cf.user_id` because they do not represent an individual Access user. +- Customer-supplied metadata keys that begin with `cf.` are reserved and are not saved. diff --git a/src/content/docs/ai-gateway/observability/custom-metadata.mdx b/src/content/docs/ai-gateway/observability/custom-metadata.mdx index 1533a4b38d6..ff9a531f15e 100644 --- a/src/content/docs/ai-gateway/observability/custom-metadata.mdx +++ b/src/content/docs/ai-gateway/observability/custom-metadata.mdx @@ -36,6 +36,14 @@ Objects are not supported as metadata values. ::: +## Reserved metadata + +Metadata keys that begin with `cf.` are reserved for metadata added by Cloudflare. Do not send your own `cf.*` metadata keys. AI Gateway removes customer-supplied `cf.*` keys before saving request metadata. + +When a request reaches AI Gateway through a [custom domain protected by Cloudflare Access](/ai-gateway/configuration/custom-domains/), AI Gateway adds the authenticated Access user ID to request metadata as `cf.user_id`. This value is the verified Access JWT `sub` claim, not the user's email address. + +AI Gateway guarantees that `cf.user_id` is saved when a valid Access user ID is present. If the request already has five custom metadata entries, AI Gateway may remove the last custom entry so `cf.user_id` can be saved. Service-token requests and requests without a user subject do not receive `cf.user_id` metadata. + ## Implementations ### Using cURL From 6ed3cedacc12e2b4b1300549b04b22986b18d1fd Mon Sep 17 00:00:00 2001 From: Kenneth Johnson Date: Wed, 1 Jul 2026 11:50:29 -0500 Subject: [PATCH 2/5] [AI Gateway] Refine Access identity changelog --- .../ai-gateway/2026-07-01-access-user-id-metadata.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/content/changelog/ai-gateway/2026-07-01-access-user-id-metadata.mdx b/src/content/changelog/ai-gateway/2026-07-01-access-user-id-metadata.mdx index 0dd547c7c18..5e785a66085 100644 --- a/src/content/changelog/ai-gateway/2026-07-01-access-user-id-metadata.mdx +++ b/src/content/changelog/ai-gateway/2026-07-01-access-user-id-metadata.mdx @@ -1,13 +1,13 @@ --- -title: Track Access users in AI Gateway metadata -description: AI Gateway now adds the authenticated Access user ID to request metadata for Access-protected custom domain traffic. +title: Identity-aware controls are now available in AI Gateway +description: Use Cloudflare Access identity in AI Gateway to set spend limits, control model access, filter logs, and more. products: - ai-gateway date: 2026-07-01 --- -AI Gateway now records the authenticated Cloudflare Access user ID in request metadata for traffic sent through an Access-protected custom domain. +AI Gateway now supports identity-aware controls through a new Cloudflare Access integration. When traffic reaches AI Gateway through an Access-protected custom domain, AI Gateway can use the authenticated user's Access identity in logs, analytics, routing, and spend controls. -When AI Gateway receives a valid Access JWT with a user subject, it adds the user's Access `sub` claim as `cf.user_id`. You can use this metadata field to filter logs, review usage, and build per-user or per-team spend controls without passing user IDs from the client application. +This means you can set per-user or per-team spend limits, control which models different users can access, filter logs by user, and build policies without passing user IDs from the client application. AI Gateway adds the verified Access user ID to request metadata as `cf.user_id`. For setup instructions, refer to [Custom domains](/ai-gateway/configuration/custom-domains/). From df866441c0c4bff9ef88b5e12d098a3a1c907071 Mon Sep 17 00:00:00 2001 From: Kenneth Johnson Date: Wed, 1 Jul 2026 12:23:20 -0500 Subject: [PATCH 3/5] [AI Gateway] Add custom domains API examples --- .../configuration/custom-domains.mdx | 94 +++++++++++++++++-- 1 file changed, 88 insertions(+), 6 deletions(-) diff --git a/src/content/docs/ai-gateway/configuration/custom-domains.mdx b/src/content/docs/ai-gateway/configuration/custom-domains.mdx index 066dfa140e2..ec236f010fb 100644 --- a/src/content/docs/ai-gateway/configuration/custom-domains.mdx +++ b/src/content/docs/ai-gateway/configuration/custom-domains.mdx @@ -8,15 +8,17 @@ products: - ai-gateway --- +import { CURL } from "~/components"; + Custom domains let you send AI Gateway requests through a hostname that you own, such as `ai.example.com`. You can then protect that hostname with [Cloudflare Access](/cloudflare-one/access-controls/applications/http-apps/) so users authenticate with your identity provider before they can call your gateway. When a request to a custom domain includes a valid Cloudflare Access JWT, AI Gateway accepts the Access JWT as the request credential. The client does not need to send an AI Gateway token for that request. AI Gateway also adds the verified Access user ID to request metadata as [`cf.user_id`](/ai-gateway/observability/custom-metadata/#reserved-metadata), so you can filter logs, analytics, and spend by the authenticated user. ## How it works -Custom domains use provider-relative paths. The hostname identifies the account and gateway, so the request path starts with the provider route rather than `/v1/{account_id}/{gateway_id}`. +Custom domains let you omit the account ID and gateway ID from request URLs. The hostname identifies the account and gateway, so requests can go directly to AI Gateway provider-native routes and OpenAI-compatible `compat` routes. -For example, if your custom domain is `ai.example.com`, an OpenAI-compatible request uses: +For example, if your custom domain is `ai.example.com`, an OpenAI provider request uses: ```txt https://ai.example.com/openai/v1/chat/completions @@ -28,9 +30,9 @@ Instead of: https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openai/v1/chat/completions ``` -Before AI Gateway forwards the request to the upstream provider, it removes Cloudflare-only credentials such as the Access JWT and AI Gateway authorization headers. +For example, `https://ai.example.com/compat/chat/completions` routes through the same gateway using the OpenAI-compatible endpoint. Before AI Gateway forwards the request to the upstream provider, it removes Cloudflare-only credentials such as the Access JWT and AI Gateway authorization headers. -## Set up a custom domain +## Set up a custom domain in the dashboard Custom domains for AI Gateway are being rolled out. If the option is not visible in your account, contact your Cloudflare account team. @@ -46,9 +48,89 @@ To add a custom domain: After setup, users can make requests to the custom domain after authenticating through Access. Requests with a valid Access user subject include `cf.user_id` in AI Gateway metadata. +## Set up a custom domain via API + +You can also create and manage custom domains through the Cloudflare API. + +:::note +The custom domains API is not yet included in the public API reference while the contract is still being finalized. +::: + +Unlike the dashboard, the API does not create the DNS record for you. After you create the custom domain, use the returned `cname_target` to create a proxied CNAME record for your hostname. + +### Create a custom domain + + + +The response includes the custom domain status and the CNAME target: + +```json +{ + "success": true, + "result": { + "hostname": "ai.example.com", + "gateway_id": "my-gateway", + "status": "pending_dcv", + "cname_target": "", + "created_at": 1782925200000, + "modified_at": 1782925200000 + } +} +``` + +### Create the DNS record + +Create a proxied CNAME record in the zone that owns your custom domain. Set `content` to the `cname_target` returned when you created the custom domain. + +", + proxied: true, + }} +/> + +The custom domain remains in `pending_dcv` until domain control validation completes. + +### List custom domains + + + +### Get a custom domain + + + +### Delete a custom domain + + + ## Example request -After the user authenticates to Access, send requests to the custom domain with the provider-relative path: +After the user authenticates to Access, send requests to the custom domain without the account ID or gateway ID in the path: ```bash curl -X POST "https://ai.example.com/openai/v1/chat/completions" \ @@ -68,7 +150,7 @@ If you call the custom domain from a non-browser client, include the Access toke ## Limitations -- Custom-domain routes are provider-relative. Do not include `/v1/{account_id}/{gateway_id}` in the path when using the custom hostname. +- Newer AI Gateway REST API endpoints are not yet supported on custom domains. - `cf.user_id` is only added when AI Gateway receives a valid Access JWT with a non-empty user subject. - Service-token requests do not include `cf.user_id` because they do not represent an individual Access user. - Customer-supplied metadata keys that begin with `cf.` are reserved and are not saved. From cd0cc5dce3127468e373c13259c957ae9a66df8b Mon Sep 17 00:00:00 2001 From: Kenneth Johnson Date: Wed, 1 Jul 2026 14:44:22 -0500 Subject: [PATCH 4/5] [AI Gateway] Clarify identity changelog spend controls --- .../changelog/ai-gateway/2026-07-01-access-user-id-metadata.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/changelog/ai-gateway/2026-07-01-access-user-id-metadata.mdx b/src/content/changelog/ai-gateway/2026-07-01-access-user-id-metadata.mdx index 5e785a66085..89068d87a5d 100644 --- a/src/content/changelog/ai-gateway/2026-07-01-access-user-id-metadata.mdx +++ b/src/content/changelog/ai-gateway/2026-07-01-access-user-id-metadata.mdx @@ -8,6 +8,6 @@ date: 2026-07-01 AI Gateway now supports identity-aware controls through a new Cloudflare Access integration. When traffic reaches AI Gateway through an Access-protected custom domain, AI Gateway can use the authenticated user's Access identity in logs, analytics, routing, and spend controls. -This means you can set per-user or per-team spend limits, control which models different users can access, filter logs by user, and build policies without passing user IDs from the client application. AI Gateway adds the verified Access user ID to request metadata as `cf.user_id`. +This means you can set spend limits by authenticated user, control which models different users can access, filter logs by user, and build policies without passing user IDs from the client application. AI Gateway adds the verified Access user ID to request metadata as `cf.user_id`. For setup instructions, refer to [Custom domains](/ai-gateway/configuration/custom-domains/). From 7b48dc8c1d6ab126fb4de8d1ee3f77e4d019b8c5 Mon Sep 17 00:00:00 2001 From: Kenneth Johnson Date: Wed, 1 Jul 2026 14:49:03 -0500 Subject: [PATCH 5/5] [AI Gateway] Clarify custom domains API note --- src/content/docs/ai-gateway/configuration/custom-domains.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/ai-gateway/configuration/custom-domains.mdx b/src/content/docs/ai-gateway/configuration/custom-domains.mdx index ec236f010fb..56709208444 100644 --- a/src/content/docs/ai-gateway/configuration/custom-domains.mdx +++ b/src/content/docs/ai-gateway/configuration/custom-domains.mdx @@ -53,7 +53,7 @@ After setup, users can make requests to the custom domain after authenticating t You can also create and manage custom domains through the Cloudflare API. :::note -The custom domains API is not yet included in the public API reference while the contract is still being finalized. +The custom domains API is not yet included in the public API. It will be added after the contract is finalized. ::: Unlike the dashboard, the API does not create the DNS record for you. After you create the custom domain, use the returned `cname_target` to create a proxied CNAME record for your hostname.