A single-level tenancy model — "you're in the org or you're not" — works right up until a real company shows up. Now there are two teams who shouldn't see each other's keys, a platform group that needs org-wide budgets, and a contractor who should touch exactly one project. NemoRouter models this with three nested scopes: org → team → member, with resources attaching at the level that matches their blast radius. This post is the model and the one security rule that holds it together.
The hierarchy
ORG (one billing entity)
└─ TEAM(S) (a "Default" team always exists)
└─ MEMBER(S) (each user in exactly ONE team within the org)
└─ resources scope at three levels:
· org — credits, billing, subscription
· team — virtual keys, team guardrails, team budgets/limits
· key — per-key guardrails, per-key RPM/TPM, per-key spendTwo invariants keep this clean: every user belongs to exactly one org and exactly one team within it, and every org has at least one team (the auto-created Default). There's no multi-team membership to reason about — "change teams" means leave and rejoin — which keeps authorization decisions unambiguous.
What scopes where, and why
The level a resource attaches to is chosen by who should be affected when it changes:
| Resource | Scope | Why that level |
|---|---|---|
| Credits, billing, subscription | Org | Money is one pool per billing entity |
| Virtual keys | Team | A key belongs to the team that uses it |
| Guardrails | Key > team > org | Strict cases override loose defaults |
| Budgets / rate limits | Org / team / key | Cap at whichever blast radius you mean |
| Per-key spend | Key | Attribution is per key |
Credits live at the org because the bill is one bill. Keys live at the team because that's the unit that owns and uses them. Guardrails resolve most-specific-first so a sensitive key can be locked down without weakening the org default. The pattern is consistent: attach the control at the level whose blast radius it's meant to bound.
The security rule: team identity comes from auth, never the request
Here's the load-bearing rule. The active team for a request is read from the authenticated context — resolved from the API key the caller authenticated with — never from a field in the request body or query string.
Trusting request-supplied team_id is a spend-attribution exploit
If the gateway took team_id from the request body, a caller could attribute their spend to another team — draining a rival team's budget or hiding their own usage. So team identity for any authorization or attribution decision comes only from the authenticated key. The request can say anything; the gateway believes only the context.
This mirrors why rate limits and A/B assignment aren't request-overridable: anything that decides authorization or attribution must come from a source the caller can't forge. The team does flow outward into provider metadata for tracking — but it's sourced from the authenticated context, not echoed from the caller's input.
Enforced in depth, not just at one layer
Team scoping isn't only application logic — it's enforced underneath the application too, at the data layer. Team-scoped reads are filtered by the authenticated team, so even an application bug that forgets a team filter can't leak another team's keys: the lower layer refuses the rows. Defense in depth — the app scopes, and the data layer scopes again underneath it.
The Default team and why it matters
Every org gets a Default team at creation, and it can't be deleted while it has members. This avoids a nasty edge case: an org with zero teams is an org where keys have nowhere to live and new members have nowhere to land. Guaranteeing at least one team means the "where does this key go" question always has an answer, and onboarding never hits a teamless dead-end.
The takeaway
Real organizations are nested, so the tenancy model is too: org for money, team for keys and shared policy, key for per-use limits and attribution — each control attached at the blast radius it's meant to bound. The rule that makes it safe is simple and absolute: team identity for any authorization or attribution decision comes from the authenticated context, never the request. Set up teams in the dashboard; it's the same org-team-member model end to end.
