Team Context
Know when a request selects one team and when it is partner scoped
Most accounting resources belong to one team. Select that team with:
x-team-id: <team-id>Route Shapes
| Shape | Example | Selection |
|---|---|---|
| Regional portfolio | Teams, issues | x-data-region |
| Partner/catalog | GET /partner, GET /apps | No managed-team selector |
| Team singleton | GET /team | x-team-id for multi-team credentials |
| Team resource | GET /transactions | x-team-id for multi-team credentials |
| User bootstrap | GET /me | Optional; response identifies resolved team |
| Embedded call | Allowed classified read with session bearer | Session's team; header optional |
Do not send two competing team selectors. An embedded session is already bound
to the team it was issued for: x-team-id is unnecessary there, and sending
an x-team-id that names a different team is rejected with 403. The team ID
in the response is the selected context; store it with any team-scoped client
cache. Embedded sessions cannot use allowTeamFallback; losing access to the
signed team ends that session instead of selecting another membership.
Switching Teams
When the user switches teams:
- cancel or ignore in-flight requests for the old team;
- replace the request header;
- clear team-scoped entities, issues, cursors, and snapshots;
- load the new team bootstrap state; and
- establish new webhook or polling state for that team.
Resource IDs do not grant cross-team access. The API verifies both the credential's access scope and the selected team's ownership of referenced resources.
Switching Partner Portfolio Regions
When GET /me resolves a partner team, partnerContext.managedTeamRegions
lists every region containing active or inactive managed teams. Each entry has
the region's API base URL and active/inactive counts. This is discovery
metadata from the control plane, not a merged business-data result.
For a supported portfolio read, send:
x-data-region: usx-team-id and x-data-region have different meanings: the first is the
authorization/current-team context, while the second selects one regional
data partition. The API reads one region per request. Call the advertised
regional endpoints independently when the UI needs more than one region, and
keep page/cursor state per region. Do not send x-data-region as a substitute
for x-team-id on team-scoped routes.