Teams

Teams in Shoehorn represent engineering groups that own and operate services. They form the backbone of ownership, RBAC, and organizational structure.

Creating Teams

Via the UI

1. Navigate to Organization > Teams
2. Click Create Team
3. Fill in the team details:
   • Name: Display name (e.g., “Platform Engineering”)
   • Slug: URL-friendly identifier (e.g., platform-engineering)
   • Description: What the team does
   • Parent Team: Optional hierarchical parent
4. Click Create

Via the API

curl -X POST https://shoehorn.example.com/api/v1/admin/teams \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Platform Engineering",
    "slug": "platform-engineering",
    "description": "Manages shared infrastructure and platform services",
    "parent_team_id": null
  }'

Team Members

Adding Members

curl -X POST https://shoehorn.example.com/api/v1/admin/teams/<team-id>/members \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "<user-uuid>",
    "role": "member"
  }'

Member Roles

Role	Description
owner	Full control over the team
manager	Administrative control
lead / team_lead	Technical leadership
member	Regular team membership

Updating a Member’s Role

curl -X PATCH https://shoehorn.example.com/api/v1/admin/teams/<team-id>/members/<user-id> \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"role": "lead"}'

Team Hierarchy

Teams can have parent-child relationships to model organizational structure:

Engineering (root)
  ├── Platform Engineering
  │   ├── Infrastructure
  │   └── Developer Experience
  ├── Product Engineering
  │   ├── Payments Team
  │   └── User Team
  └── Data Engineering

Set a parent team when creating or updating:

curl -X PUT https://shoehorn.example.com/api/v1/admin/teams/<team-id> \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"parent_team_id": "<parent-uuid>"}'

Circular references are prevented at the database level.

Team Details Response

When fetching a single team, the response includes:

{
  "team": {
    "id": "550e8400-...",
    "name": "Platform Engineering",
    "slug": "platform-engineering",
    "description": "...",
    "parent_team_id": null,
    "member_count": 8
  },
  "members": [...],
  "group_mappings": [...],
  "audit_log": [...]
}

Team Metadata

Teams support a flexible JSONB metadata field for custom attributes:

curl -X PUT https://shoehorn.example.com/api/v1/admin/teams/<team-id> \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "cost_center": "CC-1234",
      "slack_channel": "#platform-eng",
      "oncall_rotation": "platform-primary"
    }
  }'

Browsing Teams

The teams page supports:

• Search: Filter by name, description, or ID
• Size filter: Small (1-5), Medium (6-15), Large (16+)
• Sorting: By name, size, or creation date
• Pagination: 20, 50, or 100 per page

Looking Up Teams

Teams can be fetched by UUID or slug:

# By UUID
curl https://shoehorn.example.com/api/v1/teams/550e8400-...

# By slug
curl https://shoehorn.example.com/api/v1/teams/platform-engineering

Both return the same TeamDetailsResponse with members, group mappings, and audit log.