Managing Teams

What Are Teams?

Teams group users together for:

• Approval workflows (e.g., “platform team must approve production changes”)
• Access grants (e.g., “give the security team read access to all workspaces”)
• API key attribution (e.g., “this key belongs to the DevOps team”)

Creating a Team

POST /teams
{
  "name": "Platform Team",
  "description": "Manages production infrastructure"
}

Requires org owner or admin role.

Team Management

Adding Members

POST /teams/{id}/members
{
  "user_id": "user-uuid"
}

The user must already be a member of the org. The operation is idempotent — adding an existing member is a no-op.

Removing Members

DELETE /teams/{id}/members/{userId}

IdP-Managed Teams

Teams synced from an identity provider (Okta, Azure AD, etc.) have managed_by: "idp". These teams:

• Cannot be edited — PATCH returns 409 Conflict
• Cannot have members added or removed — returns 409 Conflict
• Can be deleted — but this removes the Forgecroft record (not the IdP team)

Only edit IdP-managed teams through your identity provider.

Using Teams in Governance

Teams are used in approval rules:

{
  "name": "platform-approval",
  "approver_type": "team",
  "approver_id": "team-uuid",
  "min_approvals": 1,
  "condition": { "type": "destroyed_gt", "value": 0 }
}

And in access grants:

{
  "subject_type": "team",
  "subject_id": "team-uuid",
  "verb": "read",
  "resource_type": "workspace",
  "resource_id": "workspace-uuid"
}

Related API Endpoints

• POST /teams — Create a team
• GET /teams — List all teams
• GET /teams/{id} — Get a team with members
• PATCH /teams/{id} — Update a team
• DELETE /teams/{id} — Delete a team
• POST /teams/{id}/members — Add a member
• DELETE /teams/{id}/members/{userId} — Remove a member