Teams API

No projects. The old "project" idea split in two: the app grouping is now deployments (apps sharing a cluster/namespace destination — see Applications), and the access boundary is scoped role bindings (role_bindings table). /api/projects endpoints return 404 — this page (renamed from it) covers the org/team side only.

Teams are org-scoped groups — their ids feed role_bindings subjects, so a binding can grant a whole team sync access to one deployment.

Model

Organization (Better Auth)
  ├── Members — org roles: Owner / Admin / Contributor / Viewer
  ├── Teams   — groups of members (this API)
  └── Role bindings — (team|user) × (admin|sync|read) × (org|cluster|deployment) scope

Org management and membership runs through Better Auth's organization plugin in the platform app (/api/auth/*), not the Go API.

Endpoints

List Teams

GET /api/v1/teams

Permission: team:read (all org roles).

{
  "teams": [
    {
      "id": "abc123",
      "name": "platform",
      "member_count": 4,
      "created_at": "2026-01-10T09:00:00Z"
    }
  ]
}

Create Team

POST /api/v1/teams

Permission: team:manage (org Admin/Owner). Body: { "name": "platform" } — the creator becomes the first member.

{ "team": { "id": "abc123", "name": "platform", "member_count": 1, "created_at": "…" } }

409 on a duplicate name in the org.

What teams can't do here

Capability	Where it lives
Add/remove members	Better Auth team plugin (`/api/auth/organization/*` in the platform app)
Grant/revoke scoped roles	`role_bindings` — managed in the platform UI's access page
Org settings, invitations	Better Auth organization plugin

Scoped roles

Bindings grant read | sync | admin over a scope — see RBAC:

org scope — everything in the org (or use org roles instead)
cluster scope — one registered cluster (scope_id: "prod-cluster")
deployment scope — one deployment (scope_id: "prod-cluster/default")

RBAC — org roles, scoped bindings, permission matrix
Authentication — Better Auth owns org/member management
Audit API — team.create is audited

Teams

On this page