Teams and approvals

Tested with: Portal teams flow · zb-auth role matrix · Team and Enterprise plans

Enterprise account (optional: consolidated invoice, global policies, SSO/SCIM)
└── Organization (billing entity; plan, subscription, BAA, default region)
    ├── Members and service accounts with org roles
    └── Teams (departments / squads)
        ├── Team members with team roles
        ├── Team quota + budget (subset of the org's)
        └── Projects
            └── Instances (tagged with team, project, cost centre)

Every org has a default team (“Everyone”), so small orgs never see the concept. Teams are one per org on Free and Solo and unlimited on Team and Enterprise.

Roles

Scope	Role	Can
Org	Owner (`owner`)	Everything, including delete org, transfer ownership, sign the BAA; cannot be restricted
Org	Admin (`admin`)	Manage members, roles, teams, quotas, budgets, SSO, API keys, billing and all instances
Org	Developer (`developer`)	Create and change instances and projects, reveal credentials, backups and restore; no deletes, no people
Org	Read-only (`viewer`)	View projects, instances, backups and usage; no credentials, no changes
Org	Billing (`billing`)	Plan, payment methods, invoices and usage; no instance access
Org	Auditor (`auditor`)	Read the audit log and usage only
Org	Project access only (`member`)	No org-wide access; capabilities come from project roles and team roles
Project	Admin, Developer, Read-only	The org role’s instance, credential and backup permissions, on assigned projects only (Team and Enterprise)
Team	`lead`	Manage team members and quota within org limits; approve requests
Team	`developer`	Create, modify, delete instances in the team’s projects within quota; reveal credentials; backups and restore
Team	`operator`	Resize, pause/resume, backups, rotate credentials; cannot create or delete
Team	`viewer`	Read-only, no credentials
Any	Custom roles (Enterprise)	Permission sets composed from the matrix

On Team and Enterprise you can adjust what the predefined org roles allow (the owner stays fixed) and give people roles on single projects. The full permission matrix and the editing rules are in Roles and permissions.

Service accounts are members with an API key and a role; they cannot sign in interactively. An API key inherits the intersection of its owner’s role and its scopes.

Seats

Seats, teams and service accounts per plan
Plan	Included seats	Extra seat	Teams	Service accounts
Free	1 (the owner)	not available (move to Team)	1	1
Solo	1 (the owner)	not available (move to Team)	1	3
Team	Unlimited	included	unlimited	unlimited
Enterprise	Unlimited	included	unlimited + subsidiaries	unlimited

Solo is a single-seat plan: to invite collaborators, upgrade the org to Team.

A seat is a human member with any role above auditor; auditors and service accounts do not consume seats.

Quotas, budgets and approvals

Control	Set by	Enforced where
Org quotas (instances, storage, egress, sizes)	plan + admin overrides	metering, before creation
Team quota	org admin or team lead within the org quota	metering, per team
Team budget (USD / month)	org admin	billing computes spend per team; the API refuses creations that would exceed it unless approved
Approval threshold	org admin (“sizes above m4 or secure placement need lead approval”)	the API creates an approval request instead of an instance
Allowed engines, regions, placements, max size per team	org admin	API validation

zb teams create --name Platform --slug platform --cost-centre CC-4410 --budget-cents 250000
# Policy, allowed engines and max size are set in the portal or through the API:
zb api PATCH /v1/orgs/{org}/teams/<team-id> -d '{
  "allowed_engines": ["postgres", "valkey"],
  "quota": { "max_size": "m4" },
  "approval_policy": { "sizes_above": "m4", "placements": ["secure"] }
}'
zb approvals list            # as a lead
zb approvals approve apr_01J9... --reason "Q4 load test"

Requesters see the request status on the instance list; leads approve in the portal or from the email link. Requests expire after 7 days. Every approval is audited with requester, approver and reason.