Files
coder/docs/coder-agents/platform-controls
Sas Swart 4ac8f0a2aa docs: document how AI Gateway assigns a request's organization (#31925)
Documents how AI Gateway assigns every request to one organization, and
how that organization now decides the effective group, budget,
overrides, and spend. Adds a **Request organization** page and corrects
pages that still described budget resolution as deployment-wide.

Refs AIGOV-753. Describes behavior merged in #30902, #31118, #31119,
#31120, #31121, #31583, and #31584.

## Changes

- New page `docs/ai-governance/ai-gateway/request-organization.md`
(sidebar, after Cost control): resolution order, the effective group
fallback, rejected requests, what the organization controls, a multi-org
worked example, reports that still resolve across all orgs, and the
caveat for standalone gateways older than v2.40.
- `cost-controls.md`: removes "the effective group is deployment-wide",
scopes overrides and effective group resolution to the request's
organization, and adds the reporting caveat.
- `standalone.md`: older replicas check budgets across all
organizations.
- `coder-agents/platform-controls/{index,spend-management}.md`: these
said an override beats every group budget, which is no longer true for
chats in another organization.

## For reviewers

- **Mismatch rejection is not documented.** The ticket and RFC describe
rejecting a workspace/chat org mismatch. A chat can only bind a
workspace in its own org (`coderd/exp_chats.go`), chatd requests resolve
to the chat's org even with a workspace, and no client request can carry
both inputs. The page says the two always agree instead.
- **"v2.40" is inferred.** `release/2.39` is on aibridged API v1.5 and
`main` is on v1.6, so v1.6 ships in v2.40. A 2.39.x backport would make
this wrong.
- **Custom prices.** The price lookup reads per-org prices, but no API
or CLI can set them yet, so the page says custom prices apply in every
org. This needs an update when per-org prices ship.
- **Site-wide reports.** The avatar menu, Agents usage indicator, `GET
/api/v2/users/{user}/ai/spend`, Members tab budget, Groups page combined
limit, and `blocked_users` metric still resolve across all orgs
(`TODO(AIGOV-527)`), so they can disagree with what was enforced.

## Release note draft

```markdown
- AI Gateway budgets and spend follow the request's organization (#31119, #31120, #31121, #31583, #31584)

  > Every AI Gateway request now belongs to one organization: the workspace's organization for workspace session tokens, the chat's organization for Coder Agents, and otherwise the organization of the user's effective group. Budgets, user overrides, and spend apply within that organization only, instead of across all of the user's organizations. Users in one organization see no change. Users in several organizations can hit a smaller budget, or have no limit at all, in another organization's workspaces and chats. Requests are rejected when the user is no longer a member of the workspace's or chat's organization, or of any organization.
  >
  > Migration: Set budgets in every organization your users send AI requests from. Upgrade standalone AI Gateway replicas to v2.40. Older replicas keep checking budgets across all organizations until upgraded.
```

## Validation

`make pre-commit-light`, Vale on the changed files, and `make
lint/docs-manifest` pass. A `doc-check` author self-check found 13
blocking findings, all fixed. Not applied: a suggested test pinning the
site-wide spend endpoint (code change, out of scope for this docs PR).

<details>
<summary>Decision log and verified behavior</summary>

Sources: AIGOV-753, epic AIGOV-749 and its delivered tickets (AIGOV-712
to 716), the canceled AIGOV-717, and the RFC "AI Gateway Model RBAC and
Org-Scoping" (Phase 1).

Verified against `main` (`a3aab79775`):

| Claim | Evidence |
|---|---|
| Order: workspace session token, chat org, site-wide effective group |
`coderd/aibridgedserver/orgresolver.go` `resolveOrganization` |
| Workspace session token = `coder_workspace_owner.session_token` |
`provisionerdserver.WorkspaceSessionTokenName`, `workspaceAttribution`
(API tokens excluded) |
| Rejections return `403 unauthorized` | `coderd/aibridged/http.go`
IsAuthorized failure path |
| Rejected: deleted workspace, not a member of the workspace/chat org or
org deleted, no live org | `orgresolver.go` `ErrUnknownWorkspace`,
`ErrUnknownOrganizationMember`, `ErrNoOrganization` |
| Chat request takes chat org even with a workspace |
`enterprise/aibridged_integration_test.go` "delegated organization with
workspace" |
| With an org, only that org's groups, override, and Everyone group
count | `coderd/aibridge/budget/budget.go`, #31119 |
| Fallback with no budgets: default org, then earliest membership |
`GetUserEveryoneFallbackGroup` |
| Budget counts only spend recorded against its group |
`GetUserAISpendSince` keyed on `effective_group_id` |
| Notifications use the per-request effective group |
`coderd/aibridgedserver/notifications.go` |
| Per-org prices not settable |
`UpsertOrganizationAIProviderModelConfig` has no non-test caller |
| v2.39 gateways: site-wide budget check, no org recorded |
`release/2.39` `coderd/aibridged/http.go`,
`aibridge/recorder/drpc_recorder.go` |

Page vs. section: a dedicated explanation page, because
`cost-controls.md` is already long and RFC Phases 3 and 4 (model RBAC,
"require organization scope") will build on the same resolution rules.

</details>

---

*This PR was generated by Coder Agents on behalf of @SasSwart.*
2026-11-17 09:51:14 +02:00
..