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: a surface contributes a single per-execution cost/tokens pair whether it’s an LLM surface, a Memory surface, or any future type. Per-member ceilings live on the member itself; a team owns only its team-wide caps.
- 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 Monthly Budget and Monthly 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 |
|---|---|---|
| ID | Server-assigned UUID | Doubles as the storage filename and the identity that links members to this team. |
| Name | Required | Must be non-blank. |
| Description | Not set | Free-text description. |
| Status | Enabled | One of Enabled, Disabled, or Deleted. A deleted team is tombstoned: hidden from listings and ignored for attribution, but retained on disk so historical usage stays attributable. |
| System | Off | Built-in system record flag (e.g. the anonymous team). Can be disabled but never deleted. Set by the server, not the administrator. |
| Monthly Budget (USD) | Unlimited | Team-wide monthly USD ceiling across every member’s combined spend. Must not be negative. |
| Monthly Token Cap | Unlimited | Team-wide monthly token ceiling across every member’s combined usage. |
| Members | None | Member UUIDs belonging to this team. Must be non-blank and de-duplicated (validation rejects a blank or duplicate id). |
| Created At / Updated At | Set automatically | Record timestamps. |
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, with no special-case code path. |
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 actual cost/tokens a surface contributes comes from its own execution metrics, so LLM, Memory, and any future surface type share this exact config.
- Enabled attributes a surface’s usage to a caller. Most production surfaces should have it on.
- Order Caller Identity Sources from most to least trustworthy: the gate uses the first one that yields a value, so put a JWT claim or mTLS field ahead of a spoofable header.
- Enforce 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.
- Allowed Teams governs access control (who may call the surface at all), independent of whether Enforce is on.
- Allow Individual Overage only 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. A legacy single caller-email source is still accepted on read. |
| 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 validated API key’s name, treated as the caller identifier. |
Team gate
The team gate is a single, surface-type-agnostic entry point every surface handler calls to decide whether a request must be blocked, and to record its spend/tokens afterwards. It is a no-op when team attribution is absent/disabled or the member/team stores aren’t configured. Per the OPA policies concept, the team gate runs immediately after the Trust Fabric policy layer.
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
403when 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 Enforce is set, denies with
429against the member’s request/token caps over a trailing 60-second window. - Quota enforcement: when Enforce is set, denies with
429when the member’s or any of its teams’ monthly budget/token cap is reached (skipping the member’s own cap when Allow Individual Overage is set). - On allow, records the request against the per-minute window; token usage and spend are recorded after execution.
Usage tracking
Current-month spend and tokens 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 to disk so quotas survive a restart. 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 Trust Fabric layer the team gate runs immediately 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.