Teams
See Teams and attribution → for the conceptual model. This page is the field reference for the Team record, the surface-opt-in team-attribution block, and the data-plane team gate.
Team fields
A team groups members so their spend and token usage across any surface can be aggregated and capped, turning individual member caps into shared accountability: a department, a project, or a customer can share one budget instead of tracking every member’s ceiling separately. Attribution is surface-type agnostic: every surface contributes a single per-execution cost/tokens pair. Per-member ceilings live on the member itself. A team owns only its team-wide monthly caps and has no per-minute limit. The team editor has four tabs: Details, Members, Caps & Limits, and Usage, available once the team is saved.
- Grouping members into a team makes sense for reasoning about their combined spend as a unit (a department, a product surface’s caller base, a customer account) rather than tracking each member’s usage in isolation.
- Size Budget (USD) and Token cap to what the team as a whole should spend. Leave them unlimited if the grouping is only for reporting, not enforcement.
| Field | Default | Description |
|---|---|---|
| Team ID | Server-assigned UUID | The identity that links members to this team. Shown once the team is saved. |
| Name | Required | Must be non-blank. |
| Description | Not set | Free-text description. |
| Enabled (teams must be enabled to be counted at request time) | On | A disabled team is skipped at request time. Delete Team removes it from listings and from attribution; the record is kept, and its usage series are removed from the usage charts. Built-in teams can be disabled but not deleted. |
| Budget (USD) | Unlimited | On the Caps & Limits tab. Team-wide monthly USD ceiling across every member’s combined spend. Must not be negative. A cap of 0 means no cap. When enforced, requests are blocked with HTTP 429 team_quota_exceeded once spend has reached the cap. The request whose spend crosses the cap is not itself blocked. The cap resets on the first of each calendar month (UTC). |
| Token cap | Unlimited | On the Caps & Limits tab. Team-wide monthly token ceiling across every member’s combined usage. A cap of 0 means no cap. When enforced, requests are blocked with HTTP 429 team_quota_exceeded once tokens have reached the cap. The request whose usage crosses the cap is not itself blocked. The cap resets on the first of each calendar month (UTC). |
| Members | None | The members belonging to this team, set on the Members tab. |
| Created | Set automatically | Creation timestamp. |
Built-in teams
| Id | Purpose |
|---|---|
anonymous | Contains the anonymous member, so any caller resolving to no real team still lands in a team. Disabling it is how an admin requires explicit team membership. |
sandbox | Contains the sandbox member, so Sandbox (Test-panel) executions reconcile against surface totals while staying separable from real anonymous/live traffic. |
Surface attribution
Team attribution is the surface-level opt-in that decides where the caller’s identity lives and whether to enforce; turning it on is what makes per-caller cost governance possible for this surface. The cost and tokens a surface contributes come from its own execution metrics, so every surface type shares this same configuration.
- Surface use contributes to team quotas attributes a surface’s usage to a caller. Most production surfaces should have it on.
- Order Caller identity is read from (first match wins) from most to least trustworthy: the gate uses the first source that yields a value, so put a JWT claim or mTLS field ahead of a spoofable header.
- Enforce team / member limits (block at 429) blocks requests once a cap is hit instead of just recording them for reporting. Leaving it off at first lets you observe usage safely before switching enforcement on.
- Restrict surface to teams governs access control (who may call the surface at all), whether or not limits are enforced.
- Allow individuals to exceed their personal cap (team cap still applies) matters once a caller’s personal cap is meant as a soft guideline rather than a hard limit. The team-wide cap becomes the one that actually stops them.
| Field | Default | Description |
|---|---|---|
| Surface use contributes to team quotas | Off | Master switch for team attribution on this surface. |
| Caller identity is read from (first match wins) | None | Ordered places to look for the caller’s identity. The gate uses the first source that yields a non-empty value (JWT claim oid, then JWT claim email, then API key, tried in turn). At least one is required when enabled. |
| Auto-provision unrecognised verified callers into members (per Enrolment rules) | Off | When on, an unrecognised but verified caller (JWT, mTLS, or API key) is auto-provisioned into a member on first sight per the appliance’s member-provisioning config, instead of falling back to the anonymous member. Has no effect for unauthenticated callers or when no provisioning config is active. |
| Enforce team / member limits (block at 429) | Off | When on, blocks the request (HTTP 429) if the caller or any of their teams has reached a cap. When off, usage is recorded for reporting but never blocks. |
| Allow individuals to exceed their personal cap (team cap still applies) | Off | Surface-owner override: when on, a caller may exceed their personal per-member cap (only team-wide caps still block). Has no effect unless the enforce switch above is on. |
| Restrict surface to teams | None (every caller allowed) | Surface→team access mapping, selected from a dropdown of team names. When set, only callers belonging to at least one selected team may use the surface; everyone else (including the anonymous fallback, unless its team is selected) is denied (HTTP 403). This is access control and applies regardless of enforcement. |
Caller identity source kinds, as shown in the source-type dropdown:
| Kind | Carries | Verified? | Description |
|---|---|---|---|
| Request header | a header name | No | A request header, e.g. X-Caller-Email. Spoofable unless a trusted proxy sets it, never used for auto-provisioning. |
| JWT claim | a claim name | Yes | A claim on the authenticated JWT bearer token, e.g. email or oid. |
| Request body (JSON path) | a JSON path | No | A JSON Pointer (RFC 6901) into the request body, e.g. /user/email. Spoofable, never used for auto-provisioning. |
| mTLS client certificate | a binding (Email SAN | Subject CN) | Yes | A field of the verified mTLS client certificate. |
| API key owner | — | Yes | The identity an API key method produces, treated as the caller identifier: the Secret ID for API Key (secret store), or the Key ID for API Key (provider). |
Team gate
The team gate decides, for every surface type, whether a request must be blocked, and records its spend/tokens afterwards. It has no effect when team attribution is off. On an LLM Surface with team attribution off, a member’s Allowed models list is still enforced (403 model_not_allowed) for an authenticated caller that matches that member. On an LLM Surface, the team gate runs after source authentication and inbound policy (the appliance-wide policies for the surface type, then the surface’s own OPA policy), and before the surface usage limit.
Every request always resolves to some member and some team, even the built-in anonymous member and team when nothing else matches, so there’s never an unhandled case. In order, the gate:
- Extracts the caller identifier via the configured identity sources and resolves a member, falling back to auto-provisioning (if opted in) and then to the anonymous member.
- Resolves the member’s enabled teams, falling back to the anonymous team when empty.
- Access control: denies with
403when the resolved member is disabled; the caller belongs to no enabled team; or the allowed-teams list is non-empty and none of the caller’s teams are on it. - Model allow-list: denies with
403(model_not_allowed) when the member’s allowed-models list doesn’t include the requested model. A request that omits a model is never blocked here. - Per-member rate limits: when limits are enforced, denies with
429(member_rate_limit_exceeded) against the member’s request/token caps over a trailing 60-second window. - Quota enforcement: when limits are enforced, denies with
429(team_quota_exceeded) once the member’s or any of its teams’ monthly budget/token cap has been reached, skipping the member’s own cap when Allow individuals to exceed their personal cap (team cap still applies) is on. The request whose usage crosses the cap is not itself blocked. - On allow, records the request against the per-minute window; token usage and spend are recorded after execution.
Usage tracking
Spend and tokens for the current period accumulate into two bucket families, one per team (every member’s aggregate) and one per member (its combined share across every team and surface), persisted so quotas survive a restart. A team’s period resets on the first of the month (UTC). A member’s period resets on the monthly anniversary of its Resets monthly from date when one is set, otherwise on the first of the month (UTC). This is separate from the per-stage tracker used by usage limits, which is keyed by surface/stage rather than by team and member, and spans only the current month rather than an arbitrary date range.
Per-member rate caps are enforced over a trailing 60-second sliding window, independent of the monthly tracker.
Related
- Members: The Member record, identifier resolution, and auto-provisioning.
- Core configuration: Where team attribution sits among a surface’s other optional blocks.
- OPA policies: The inbound policy evaluation the team gate runs after.
- Cost and usage limits: The per-stage usage-limits mechanism, distinct from team/member monthly caps.
- Teams and attribution concept: Why attribution turns cost governance into per-team accountability.
Glad to hear it! Please tell us how we can improve more.
Sorry to hear that. Please tell us how we can improve.
Thank you for sharing your feedback so we can improve your experience.