Set up teams

A team is an org-local group of members and the active scope for product work. Teams are not tenants. They're an ACL primitive and the place where workflows, routes, artifacts, review packets, inbox decisions, and context resources live. "Platform" in Acme has nothing to do with "Platform" in Personal; they share a slug only.

Teams are always explicit. They are never silently auto-created. A new org starts at zero teams unless you name the first team during onboarding. You make or choose a team when a surface needs team-scoped work.

When you need a team

You probably need a team when:

• You want a clean scope for workflows, artifacts, context, and reviews.
• More than one person should be on the routing list for an approval gate.
• Multiple people should see a shared workflow without inviting each one individually.
• You want to grant a workflow or vault to a role ("Platform engineers") rather than enumerated humans.

You probably don't need a team when:

• Two people share everything. Direct grants between them are simpler.
• The thing you're sharing is one-off. Use a share group (ad-hoc grant) instead.

Create a team

During first-run onboarding, the team step can create the first team and attach its primary Git Resource before you enter the app. Later, use the Teams page:

1. Members → Teams tab → Create team.
2. Name it: e.g., Platform. Slug auto-suggested.
3. Optionally link the primary Git Resource for the team. This is where Viewport exports .viewport/ receipts for workflows, routes, artifacts, reviews, and context decisions.
4. Add members. Every member of a team must already be an org member.
5. Save.

What happens:

• A teams row is created with workspace_id set to your org. The unique(workspace_id, slug) constraint means the same slug can repeat across orgs.
• A team_members row is created for each member, with role inside the team (lead, member).
• If supplied, a team_resources row is created and marked primary.
• An audit event team.created is written.

Team roles

Inside a team, members can have one of two roles:

Team roles don't override org roles. An org viewer who's a team lead is still a viewer of the org's resources.

Address a team as a principal

When you share a resource (workflow, plan, vault), you can address a user, a team, or a share group:

Share with:  alice@acme.com           ← user
             Platform                 ← team in this org
             share-group: review-2026 ← ad-hoc share group

Routing works the same way: the platform expands the audience and writes an ACL entry. Members of the team see the resource through that grant.

Context is not shared this way. Team context belongs to the team, and organization rules apply across teams through policy injection. If someone needs to use or review a team's memory, add them to the team or adjust the context review policy.

Active team context

The web app keeps organization and team context separate:

• The profile section switches organizations only when your account belongs to more than one organization.
• The left navigation team selector controls the active team for team-scoped pages.
• If you open a workflow, route, artifact, or context page without a team selected, the app asks you to choose or create a team first.

API clients send the active team with X-Viewport-Team. The server verifies that the team belongs to the active organization and that the actor is allowed to use it.

Team setup readiness

The Overview page and workflow setup pages evaluate readiness for the active team, not for the whole organization. This matters in larger rollouts: the Platform team should not look ready because the Security team already has a route, workflow, or runner profile.

The readiness check includes:

• published workflows owned by the active team
• enabled workflow routes owned by the active team
• org-level runners that can claim that team's work
• runner settings and runner pool matches
• external intake health
• provider action credential bindings required by that team's workflows

API clients can inspect the same contract with:

GET /api/resources/{workspace}/workflow-setup-readiness
X-Viewport-Team: team_public_id

The response includes scope.team_id, setup checks, setup-plan steps, route rows, runner rows, and credential readiness. Treat blocked checks as pilot or production blockers before routing real provider events to that team.

Cross-org team safety

Teams are workspace-scoped, hard-enforced. The same slug in two orgs is two different teams. Cross-org leakage through team grants is prevented at the schema level: a team grant can only reference a team in the same workspace as the resource.

See Concepts: Organizations and teams for the invariants.

Archive a team

Removes the team from new routing but preserves history. Past audit events still reference the team name. Members are not removed from the org.

To hard-delete: contact us. Hard delete is rare and requires confirming there are no dependent ACL entries.

Where to go next

• Share resources. Using teams as principals.
• Approval policies. Routing decisions through teams.
• Concepts: Organizations and teams.