Managing Teams

What Are Teams?

Teams group users together for:

• Access grants (e.g., “give the security team read access to a project”)
• 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

Field	Type	Description
name	string	Team name
description	string	Human-readable description
managed_by	string	manual (created in Forgecroft) or idp (synced from identity provider)

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 Access Grants

A team can be the subject of an access grant, so every member inherits the granted verb on a resource:

{
  "subject_type": "team",
  "subject_id": "team-uuid",
  "verb": "read",
  "resource_type": "project",
  "resource_id": "project-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