Repository navigation
feat(ai-gateway): serve Claude subscriptions and company models on one base path - #7940
bartsmykla wants to merge 19 commits into
Conversation
✅ Deploy Preview for kongdeveloper ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
✅ KSAI Review: Finished Run report (federated) · 2 paid runs · $0.2956 total
Reviewing cost $0.2956; the |
There was a problem hiding this comment.
🔵 Needs a closer look
The linked implementation PR returns 404, so a reviewer with access must verify the credential-override and token-stripping guarantees and auth_source emission conditions.
No open issues 🎉
What changed in this PR
Documents Claude subscription token forwarding in AI Gateway 2.4 and the audit metadata used to identify these requests.
Changes:
- Explains when Anthropic targets forward a developer’s claude.ai token instead of a provider key, including token-removal safeguards.
- Documents the
auth-source: claude-aicost tag andai.proxy.meta.auth_sourceaudit field.
| File | Description |
|---|---|
app/ai-gateway/ai-audit-log-reference.md |
Adds the authentication-source audit field and links to the forwarding documentation. |
app/_ai_gateway_entities/ai-model.md |
Describes Claude subscription token forwarding, safeguards, and cost attribution. |
Review effort: Balanced
There was a problem hiding this comment.
🔵 Needs a closer look
The linked implementation PR returns 404, so a maintainer with access needs to verify the security-sensitive token-forwarding and credential-stripping guarantees, plus auth_source emission conditions.
No open issues 🎉
Review effort: Balanced
There was a problem hiding this comment.
🔵 Needs a closer look
The linked implementation PR returns 404, so a reviewer with access must verify the security-sensitive credential-forwarding and token-stripping guarantees and new auth_source logging behavior.
No open issues 🎉
Review effort: Balanced
There was a problem hiding this comment.
| Check | Result |
|---|---|
| Scope | Frozen scope: 2 paths, app/_ai_gateway_entities/ai-model.md and app/ai-gateway/ai-audit-log-reference.md, both read in full at head 8277430 against base 6dd36eb. |
| Mandate | default-code-review (adversarial) run over both documentation paths, with the AI Gateway, core, output-block, overload, plugin-reference and related-resource repository rules applied to the changed lines. |
| Findings | 2 Medium, 1 Low |
| Findings audit | Independent audit completed: 3 kept, 0 removed, 0 with insufficient evidence, 0 added. |
Verdict: SHIP WITH CHANGES. Two real Medium findings remain, both AI Gateway badge removals; they are correctly stated and sized. No Critical or High survives, and the reviewer missed none.
The two badge positions are not duplicates: separate files, separate edits. The pre-existing badges elsewhere on both pages sit on unchanged lines, which the core rules exclude.
The new behaviour claims rest on the private kong-ee implementation PR, not on this repository. The audit states them as unverified external premises and adds no finding that depends on them.
No missed defect added: every changed line named by the frozen request text was read, and no contradiction with a sibling page or the repository's AI Gateway spec could be shown.
|
/ksai review |
|
✅ KSAI Review: Finished Run report (federated) · 1 paid run · $0.3491 total
Reviewing cost $0.3491 |
There was a problem hiding this comment.
| Check | Result |
|---|---|
| Scope | Frozen scope: two paths, app/_ai_gateway_entities/ai-model.md and app/ai-gateway/ai-audit-log-reference.md, both read in full at head 82e5b32 against base 6dd36eb. |
| Mandate | default-code-review (adversarial) over both documentation paths. AI Gateway, core, output-block, overload, plugin-reference and related-resources repository rules applied to the changed lines. |
| Findings | None |
| Findings audit | Independent audit completed: 0 kept, 0 removed, 0 with insufficient evidence, 0 added. |
The pinned head resolves all three frozen prior findings: both {% new_in 2.4 %} badges are gone (ai-model.md:248 heading, ai-audit-log-reference.md:129 row), and the sign-in sentence at ai-model.md:256 now matches the reviewer's minimal fix.
The frozen AI Gateway rule forbids version badges on AI Gateway pages and overrides the core marker rules, so the removals were right and the Copilot review's request to add 2.4 badges is not actionable. Untouched AI Gateway lines keep older badges, and no page-level min_version bump is due.
Residual risk, not published: the behaviour claims rest on the private Kong/kong-ee#24369; the schema anchor at ai-model.md:250 could not be checked against the 16886-line spec (no search tool); the clause at ai-model.md:255 may name the token where the provider key is the removed value. No repository file settles these.
No added defect survived scrutiny: the ai-model.md:258 link and the ai-audit-log-reference.md:132 link resolve (route confirmed by ai-logs.md:28; both heading slugs match), and nothing on the changed lines contradicts a frozen rule or a repository file.
82e5b32 to
8c93eb6
Compare
cloudjumpercat
left a comment
There was a problem hiding this comment.
@bartsmykla thanks for drafting this! I left a couple suggestions
6666803 to
3d0ec9f
Compare
|
/ksai review |
|
✅ KSAI Review: Finished Run report (federated) · 1 paid run · $0.3410 total
Reviewing cost $0.3410 |
There was a problem hiding this comment.
| Check | Result |
|---|---|
| Scope | app/_ai_gateway_entities/ai-model.md, the only path in the frozen scope, read in full at head 3d0ec9f against base ce5aa2a. The diff is 140 added lines, the new Claude subscriptions of developers section, with no deletions and no other changed path. |
| Mandate | default-code-review (adversarial), with the AI Gateway, core, prose, output-block, schema-restate, related-resources, ui-inventory and plugin-reference repository rules applied to the changed lines of app/_ai_gateway_entities/ai-model.md. |
| Findings | 1 Medium, 3 Low |
| Findings audit | Independent audit completed: 4 kept, 0 removed, 0 with insufficient evidence, 0 added. |
All four candidate positions survive. The Medium at ai-model.md:530 is a real diff-versus-repository contradiction, and no finding was removed or downgraded.
Two findings were corrected: the voice finding now lists the repeated travel verb at line 538, and the link finding cites sibling entity pages as convention evidence.
External premises left unpublished: the keyless Anthropic provider, upstream_access_token_header null, the x-api-key mirroring, the model IDs and the Claude Code environment variables rest on the author's live check, not on repository files.
Coverage is complete for the single frozen path at head 3d0ec9f; no additional defect with repository evidence was found in the changed lines.
There was a problem hiding this comment.
| Check | Result |
|---|---|
| Scope | Frozen scope at head 8112baf against base ce5aa2a: app/_ai_gateway_entities/ai-model.md (new Claude Code subscription section and narrowed OIDC note), app/_ai_gateway_entities/ai-auth-strategy.md (narrowed OIDC warning) and app/_how-tos/ai-gateway/set-up-kong-identity-for-a2a.md (FAQ answer). All three files were read whole, with the schema, provider and load-balancing files the new text depends… |
| Mandate | Mandate: default-code-review (adversarial). The diff is Markdown, so no language catalog applies; the universal axes (correctness, boundaries, failure paths, hidden assumptions, described-setup security) and the frozen repository docs rules were applied to the changed lines, against the schema and sibling pages the new section depends on. |
| Findings | 1 Medium |
| Findings audit | Independent audit completed: 1 kept, 0 removed, 1 with insufficient evidence, 0 added. |
Decision: keep position 1 at Medium [risk] - the company OIDC strategy leaves the plugin default that sends the validated IdP access token upstream to Anthropic. Position 2 is insufficient_evidence: its decisive claim about the gateway's Authorization handling is not verifiable in this repository.
The candidate's other assertions held: the narrowed OIDC note now matches in all three changed files, and the route header regex, targets[].allow_auth_override, failover_criteria, scopes_claim, the keyless provider example and the changed anchors verify against repository schemas and specs.
No new defects added: the remaining changed lines, including the Claude Code settings, the header-rule routing explanation and the Limits bullets, hold on the checks made at this head.
|
/ksai review |
|
✅ KSAI Review: Finished Run report (federated) · 1 paid run · $0.7045 total
Reviewing cost $0.7045 |
There was a problem hiding this comment.
| Check | Result |
|---|---|
| Scope | Frozen scope at head 76e089b against base ce5aa2a: app/_ai_gateway_entities/ai-model.md (new Claude Code subscription section, narrowed OIDC note, corrected anchor), app/_ai_gateway_entities/ai-auth-strategy.md (narrowed OIDC warning) and app/_how-tos/ai-gateway/set-up-kong-identity-for-a2a.md (FAQ answer). All changed hunks were read. |
| Mandate | Mandate: default-code-review (adversarial). The diff is Markdown, so no language catalog applies; the universal axes and the frozen AI Gateway, Core, How-to, Prose, output-block and related-resources rules were applied to the changed lines against the schema and the sibling AI Gateway pages and cookbooks the new text depends on. |
| Findings | 1 High, 1 Low |
| Findings audit | Independent audit completed: 2 kept, 0 removed, 0 with insufficient evidence, 0 added. |
Coverage complete for the frozen scope: all hunks of base ce5aa2a..head 76e089b across the three scoped files were read, and every decisive config claim was re-checked against the AI Gateway spec, the policy schemas, the routing docs and the sibling cookbooks rather than accepted from the reviewer's summary.
The narrowed OIDC rule now reads the same in all three changed files, and no other repository page carries the old blanket rule. The section's route-apart claim is consistent with documented route precedence, where routes with more headers win (app/gateway/routing/traditional.md:496-499).
Position 1 is kept and raised to High: the documented setup leaves consumer mapping unset, so every valid IdP token that maps to no AI Consumer is terminated with 401 and both the section's promise and its flow fail. Position 2 is kept as Low [nit]. No defect was added.
Unverified and outside the repository: Claude Code client behavior, the claude.ai token format and prefix, Okta claim behavior, and the pull request's live data-plane result. No decision or assessment claim rests on them.
9a88af5 to
fbdc28c
Compare
|
/ksai review |
|
✅ KSAI Review: Finished Run report (federated) · 1 paid run · $0.6725 total
Reviewing cost $0.6725 |
On an Anthropic target at api.anthropic.com, AI Gateway forwards the claude.ai token of the developer in place of the provider key when allow_auth_override is on, or when the target has no key. Document where Kong forwards and removes the token, and the auth_source log field. Signed-off-by: Bart Smykla <bartek@smykla.com>
AI Gateway removes the claude.ai token from the headers and from the parameter that holds the provider key, not from every parameter. It skips a key that a key auth strategy accepted. Signed-off-by: Bart Smykla <bartek@smykla.com>
The field shows the credential that AI Gateway selects for the request, also when a cache answers it and no upstream request goes out. Signed-off-by: Bart Smykla <bartek@smykla.com>
AI Gateway pages carry no new_in badges. Also say that the accepted key does not go upstream. Signed-off-by: Bart Smykla <bartek@smykla.com>
The kong-ee change now forwards the token on an Anthropic target that goes to api.anthropic.com, and removes it from Authorization on every other target. It has no cost tag, no log field and no key-auth rule, so remove them from the page and from the audit log reference. Signed-off-by: Bart Smykla <bartek@smykla.com>
The earlier text described a target setting that forwards the claude.ai token. That change was reverted, so the text no longer matches the gateway. Replace it with the setup that works today: company AI Models that check the IdP token in Authorization, and keyless subscription AI Models with a -subscription alias and an x-kong-id-token header rule. Add the rules, the Claude Code settings and the limits of this setup. Signed-off-by: Bart Smykla <bartek@smykla.com>
The notes on the AI Model and AI Auth Strategy pages said that all OIDC AI Models on one base path, or in one gateway, must share one openid-connect strategy. The limit is per route: a header rule keeps two routes apart, so each route can use its own strategy. Also from review: explain what the header rule does, check that the saved strategy keeps upstream_access_token_header null, say that any SSO developer can use the subscription models, warn about API keys and apiKeyHelper that replace the subscription token, restart the client after a token refresh, narrow the context window and Okta claims, and link the entity pages. Signed-off-by: Bart Smykla <bartek@smykla.com>
The Okta org authorization server can't issue custom scopes, so the company scope check needs a custom authorization server. Both strategy examples now use the default custom server with an audience check. Also quote the base URL placeholder so the shell does not read the angle brackets as redirects, point the auth_strategies links at the auth_strategies field, not the deprecated identity_providers field, and say that Anthropic bills subscription requests to the developer. Signed-off-by: Bart Smykla <bartek@smykla.com>
Use an AI Gateway audience in both strategy examples, so that tokens that the authorization server issues for other apps fail. Tell readers to give company AI Models the same formats, capabilities and paths as the subscription example, without the header rule. Narrow the OIDC note in the Kong Identity A2A how-to to the same base path and route rule condition as the entity pages, so the pages agree. Signed-off-by: Bart Smykla <bartek@smykla.com>
Add an Authorization header rule to the subscription AI Model, so that a company token in Authorization does not match the subscription route and never reaches Anthropic. Add a Request Transformer AI Policy that removes a client x-api-key, so that only the subscription token leaves the gateway. Both were checked on a 2.4.0 data plane with real Okta and Anthropic, and through Konnect. Set upstream_access_token_header to null in the company strategy too, so that the IdP token does not reach Anthropic on company models. Signed-off-by: Bart Smykla <bartek@smykla.com>
Name the header rules and the AI Policy in the sentence that says a subscription AI Model needs both, so the reader knows which pair it is. Signed-off-by: Bart Smykla <bartek@smykla.com>
…ords Start each subsection with its subject, name the mechanism in place of travel verbs, split sentences that carried two ideas, and give the rules and limits lists a lead-in. The examples and every condition stay the same. Signed-off-by: Bart Smykla <bartek@smykla.com>
Admins and developers follow the setup step by step, so it fits a how-to better than the AI Model page. The how-to adds the company AI Models and the Claude Code settings for both groups. The AI Model page keeps a short paragraph with a link, and the OIDC notes say that a route rule lets AI Models on one base path use different strategies. Signed-off-by: Bart Smykla <bartek@smykla.com>
Readers could not get an IdP token from the Okta prerequisites, and a shell with ANTHROPIC_API_KEY from the Anthropic prerequisite replaced the subscription sign-in. The how-to now sets up the Okta app and access policy, clears conflicting credentials, pins every model role, uses the quickstart proxy URL and validates both groups. Signed-off-by: Bart Smykla <bartek@smykla.com>
The how-to now names the scopes that each Okta rule allows and requests, says where the proxy URL comes from in each shell, and gives the real effect of a shared model ID: the two AI Models share one model entry on the data plane. Signed-off-by: Bart Smykla <bartek@smykla.com>
Another rule on the Okta server could grant the company scope, and the OIDC notes read as if every AI Model had to use OIDC. The how-to also gives the proxy URL to company developers and the model ID rule for every AI Model. Signed-off-by: Bart Smykla <bartek@smykla.com>
An Okta policy for all clients with a higher priority could block the company scope, and env entries in Claude Code settings files replace the shell values that the how-to sets. Signed-off-by: Bart Smykla <bartek@smykla.com>
fbdc28c to
36fc348
Compare
There was a problem hiding this comment.
| Check | Result |
|---|---|
| Scope | Frozen scope at head fbdc28c against base 0ab7231: the five scoped paths, all hunks read. The new how-to was read whole; the other four files change a few lines each. |
| Mandate | Mandate: default-code-review (adversarial). The diff is Markdown, so no language catalog applies; the universal axes and the frozen AI Gateway, Core, How-to, Prose, landing-page, output-block and related-resources rules were applied to the changed lines. |
| Findings | 2 Low |
| Findings audit | Independent audit completed: 2 kept, 0 removed, 0 with insufficient evidence, 0 added. |
All five frozen paths were read at head fbdc28c against base 0ab7231, including the complete new how-to. Both candidate findings were re-verified at their cited lines and hold as Low; no defect imported from outside the repository was asserted.
No new defect was added. The OIDC consumer-mapping issue that earlier reviews published for this same content is still present at this head, now inside the new how-to's two strategies; the candidate disclosed it and this audit does not duplicate it, so it stays open from those earlier reviews.
The how-to's decisive config claims agree with repository sources: the ~* route-header regex rule, upstream_access_token_header: null, the policy schema fields, the include paths and the sibling validation tag all check out.
The landing page card now reads like the other Claude Code cards, and the A2A FAQ links config.route.headers as the two entity pages do. Signed-off-by: Bart Smykla <bartek@smykla.com>
cloudjumpercat
left a comment
There was a problem hiding this comment.
Left some comments!
|
|
||
| * An `openid-connect` AI Auth Strategy that reads the IdP token from `x-kong-id-token`. | ||
| * An Anthropic AI Model Provider without a key. | ||
| * A [Request Transformer](/ai-gateway/policies/request-transformer/) AI Policy that removes `x-api-key` from the request. |
There was a problem hiding this comment.
When I reviewed this last, I thought it said or was implemented in a way that AIGW automatically stripped these without a policy. Just want to confirm that this bullet is accurate with the current implementation.
There was a problem hiding this comment.
Yes, it is accurate. The automatic strip was reverted before 2.4, so the Request Transformer policy is what removes a client x-api-key now.
Move the Okta setup into a prereq include with steps in the Admin Console, add the PKCE steps that get the IdP token, and add a limit: subscription developers can use only the models that have a subscription AI Model. Apply the wording suggestions from the review. Signed-off-by: Bart Smykla <bartek@smykla.com>

Description
Some developers sign in to Claude Code with their own Claude subscription. Others use the Claude models that the company pays for. The docs don't say how both groups can share one AI Gateway base URL, and the notes on OIDC strategies say that it can't work.
This PR adds the how-to "Serve Claude subscriptions and company Claude models on one AI Gateway base URL":
Authorizationfor a required scope (scopes_claim: [scp]on Okta), keep it from Anthropic, and call Anthropic with the provider key.-subscriptionmodel ID, a keyless Anthropic provider, route header rules onx-kong-id-tokenand on a claude.ai token inAuthorization, and a Request Transformer AI Policy that removes a clientx-api-key. They send only the claude.ai token to Anthropic.The AI Model page keeps a short paragraph with a link to the how-to, and the AI CLIs landing page gets a card for it. The notes on the AI Model page, in
ai-auth-strategy.mdand in the Kong Identity A2A how-to said that all AI Models on one base path (or in one AI Gateway) that use OIDC must reference the sameopenid-connectAI Auth Strategy. They now say that AI Models with the same route match conditions must, and that a route rule such asconfig.route.headerslets them use different strategies.Question for reviewers
@gperanich @baumac, this setup uses two
openid-connectstrategies on one base path, and the header rules keep the two routes apart. Can you confirm that a header-refined route may use its own strategy?Testing
Vale and the frontmatter validator pass. The PKCE commands make a valid S256 verifier and challenge. The Okta Admin Console steps still need a check on the release candidate. The how-to uses the same entities as two live checks on a current AI Gateway 2.4 data plane with a real Okta token:
x-kong-id-tokenand withoutx-api-key.scopes_claim: [scp].ANTHROPIC_AUTH_TOKENset to the IdP token.Preview Links
https://deploy-preview-7940--kongdeveloper.netlify.app/ai-gateway/use-claude-subscriptions-with-ai-gateway/
Checklist