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..89068d87a5d --- /dev/null +++ b/src/content/changelog/ai-gateway/2026-07-01-access-user-id-metadata.mdx @@ -0,0 +1,13 @@ +--- +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 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 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/). 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..56709208444 --- /dev/null +++ b/src/content/docs/ai-gateway/configuration/custom-domains.mdx @@ -0,0 +1,156 @@ +--- +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 +--- + +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 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 provider 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 +``` + +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 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. + +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. + +## 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. 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. + +### 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 without the account ID or gateway ID in the 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 + +- 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. 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