178 lines
4.5 KiB
Markdown
178 lines
4.5 KiB
Markdown
# 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.
|
|
|