# 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`):

```json
{
  "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](enums.md) for the full permission constant list.