Organizations
Organization boundaries, customer administration, team budgets and platform authority.
For the customer workflow, start with Organizations and teams. This page describes the administration boundary behind it.
Organization
An organization owns membership, settings and governance, and identifies the billing subject for its wallet. A personal organization uses the same billing machinery as a shared organization. An admitted user can create an organization; provisioning completes its durable core/auth/billing relationship and makes the creator its owner.
The browser's active organization controls active-org management APIs. Existing API keys use their own immutable bound organization and payer. Changing browser context does not rebind existing credentials.
| Task | Surface | Authority |
|---|---|---|
| List memberships / switch context | /v1/me/organizations, /v1/me/active-organization | Caller identity and destination membership |
| Create organization | POST /v1/organizations | Authenticated admitted caller; provisioning rules apply |
| Read member roster | GET /v1/admin/active-org/members | org.members.view in the acting organization |
| List suspended members | GET /v1/admin/active-org/members/suspended | org.admin in the acting organization |
| Read teams and rosters | GET /v1/admin/active-org/teams and team read routes | org.members.view, plus resource containment |
| Manage members, teams and invitations | Active-org management routes | Organization administration and operation-specific owner protections |
| Manage organization settings | /v1/admin/active-org/settings | org.admin |
| Manage budgets and organization usage | Active-org usage/usage-limit routes | org.usage_limits.manage |
| Read Insights (sessions, people, digests) | /v1/admin/active-org/usage/analytics/activity*, /sessions* | org.admin, plus the organization's insights feature (insights_prompt_summaries for generated text) |
| Browse, label and export captured data | /v1/admin/active-org/captures*, /capture-settings, /capture-destination | org.admin, plus the organization's data_capture feature; see Data capture |
| Generate and download monthly usage reports | /v1/admin/active-org/usage-reports*, /usage-report-settings | org.admin and a management-class key, plus the organization's usage_reports feature; see Monthly reports |
| Read / manage billing | /v1/billing/* | org.billing.view / org.billing.manage; key class also applies |
Query and mutation payloads use the identifiers specified by each endpoint. Do not substitute an organization public ID for a numeric ID or derive a payer from a display name.
The member roster, the People directory and its member count, and the team and budget pickers list only accounts that can act. A member whose account a platform administrator has suspended is left out; their membership and role are kept, and they reappear when the account is re-activated. An organization administrator can still list such members, flagged "suspended": true, at GET /v1/admin/active-org/members/suspended, and can remove them or change their role through the member routes. The web app does not show suspended members.
Organization roles
| Role | Responsibility |
|---|---|
| Owner | Organization governance, including protected ownership/lifecycle operations. |
| Admin | Organization administration without owner-only deletion or ownership transfer authority. |
| Billing Admin | Credit, payment settings, usage visibility and budgets through the three billing/limit permissions. |
| Member | Permitted member/team directory reads and personal credential/usage surfaces. |
Owner floors prevent removing the final eligible owner. Custom/derived-role creation is frozen, and manager is retired. Use supported roles and permission-based gates; see Access control.
Teams
A team belongs to exactly one organization and may sit under another team of that organization (up to five levels; core migration 000113). Its roster groups existing members and can receive pending invitees through invitation team selection. Reading the directory does not grant team management or unrestricted analytics access. Structure changes (create, move, retype, archive, delete) require org.admin; team roles stay per team and do not flow down to sub-teams. Analytics reads accept include_descendants=true to widen a team filter to the team and everything beneath it; attribution itself stays on one team per key.
A personal key can hold immutable default-team attribution. Auth resolves that membership with the credential and refuses unavailable attribution; it does not fall back to unassigned traffic. Every creation form asks for the team, and an explicit No team attribution is one answer. A key created before that question derives its team from the owner's live membership in the key's organization, and that derived attribution moves with membership instead of refusing the key; the key's attributed_team_id and the key list show which case applies. Service-account team ownership is distinct from that personal-key field.
Invitations
Invitations persist before email delivery, retain delivery status and can retry delivery using the same credential. Pending team selections are editable before consumption. The recipient must match the invited email. Acceptance grants organization membership before team membership and can recover partial completion without overwriting existing roles.
SMTP acceptance is not proof of inbox delivery. Revoking an outstanding invitation stops future acceptance/recovery, but does not undo membership already granted. Completed links do not replay grants after a later removal.
Usage limits
Budgets independently match platform, organization, team and user policies. Organization-managed team/member policies remain anchored to that organization. Applicable parent constraints still apply. Calendar-month windows start at 00:00 UTC on the first day; fixed durations preserve their own semantics.
Team budgets govern attributed traffic, not every call by every person in the roster. Budgets, wallet credit and request-cost analytics are separate. See Budgets and limits.
The platform boundary
Platform authority does not confer authority inside each organization. Cross-tenant lifecycle, provider/model administration and deployment settings belong in the separate platform console. Tenant member/settings/budget actions require tenant-scoped authority.
Where configured, an authorized operator can use the audited organization-owner impersonation workflow to act through an owner's session. It requires ADMIN_IMPERSONATION_ENABLED and an available owner; it is not a general platform-to-tenant permission fallback.
The organization Access control and account Sessions pages remain placeholders, not complete editors. Model/provider access-policy evaluation is not integrated into inference. Customer documentation must not promise these as working controls.