core/docs/ICD/teams.md

Teams & Access Control

My Teams

GET /teams/mine                     → { "teams": [...] }

Returns teams the current user is a member of.

Team Administration

Team-admin-scoped routes (require RequireTeamAdmin middleware):

Team CRUD (platform admin):

GET    /admin/teams                  → { "teams": [...] }
POST   /admin/teams
GET    /admin/teams/:id
PUT    /admin/teams/:id
DELETE /admin/teams/:id

Members:

GET    /admin/teams/:id/members      → { "members": [...] }
POST   /admin/teams/:id/members      ← { "user_id", "role" }
PUT    /admin/teams/:id/members/:memberId  ← { "role" }
DELETE /admin/teams/:id/members/:memberId

Team-scoped routes (team admin, not platform admin):

GET    /teams/:teamId/members
POST   /teams/:teamId/members        ← { "user_id", "role" }
PUT    /teams/:teamId/members/:memberId
DELETE /teams/:teamId/members/:memberId

Team Providers:

GET    /teams/:teamId/providers      → { "configs": [...] }
POST   /teams/:teamId/providers      ← { "name", "provider", "endpoint", "api_key", ... }
PUT    /teams/:teamId/providers/:id
DELETE /teams/:teamId/providers/:id
GET    /teams/:teamId/providers/:id/models  → { "models": [...] }

Team Models:

GET /teams/:teamId/models           → { "models": [...] }

Available models for this team (global + team-scoped).

Team Personas: See §4.2.

Team Roles:

GET    /teams/:teamId/roles          → { "roles": [...] }
PUT    /teams/:teamId/roles/:role    ← { "permissions": {...} }
DELETE /teams/:teamId/roles/:role

Team Audit:

GET /teams/:teamId/audit             → paginated audit log
GET /teams/:teamId/audit/actions     → { "actions": [...] } (distinct action types)

Team Usage:

GET /teams/:teamId/usage             → { "totals": {...}, "results": [...] }

Groups & Resource Grants

Groups are ACL containers that decouple access from team membership. A resource grant controls who can see a Persona or KB beyond its base scope.

My Groups:

GET /groups/mine                     → { "groups": [...] }

Admin Group CRUD:

GET    /admin/groups                 → { "groups": [...] }
POST   /admin/groups                 ← { "name", "scope", "team_id" }
GET    /admin/groups/:id
PUT    /admin/groups/:id
DELETE /admin/groups/:id

Group Members:

GET    /admin/groups/:id/members     → { "members": [...] }
POST   /admin/groups/:id/members     ← { "user_id" }
DELETE /admin/groups/:id/members/:userId

Resource Grants:

GET /admin/grants/:type/:id          → { "grant": {...} }
PUT /admin/grants/:type/:id          ← { "grant_type": "team_only|global|groups", "group_ids": [...] }
DELETE /admin/grants/:type/:id

:type is persona or kb. :id is the resource ID.

Grant types:

grant_type	Visibility
team_only	Only the owning team
global	All authenticated users
groups	Members of specified groups

Permissions

Groups carry fine-grained permissions. Permission resolution: union of all group permissions + Everyone group permissions.

List all permissions:

GET /admin/permissions               → { "permissions": ["model.use", "kb.read", ...] }

Get user's effective permissions:

GET /admin/users/:id/permissions     → { "permissions": [...], "groups": [...] }

Returns the resolved permission set and contributing groups.

Group permission fields (set via PUT /admin/groups/:id):

{
  "permissions": ["model.use", "kb.read", "channel.create"],
  "token_budget_daily": 100000,
  "token_budget_monthly": 3000000,
  "allowed_models": ["claude-sonnet-4-20250514", "gpt-4o"]
}

Field	Type	Description
permissions	string[]	Permission constants granted to members
token_budget_daily	int/null	Daily token ceiling (NULL = unlimited)
token_budget_monthly	int/null	Monthly token ceiling (NULL = unlimited)
allowed_models	string[]/null	Model allowlist (NULL = unrestricted)

Everyone group: System-seeded group (ID 00000000-0000-0000-0000-000000000001) whose permissions apply to all authenticated users implicitly (no membership row needed). Editable by admins, cannot be deleted (source=system).

RequirePermission middleware: Routes gated by permission check user's resolved permission set. Returns 403 if the required permission is not present.

See enums.md for the full permission constant list.