APIIdentity & Access

Groups API

Groups enable multi-tenant RBAC by aggregating users under a shared role. When a user is added to a group, they inherit the group's permissions in addition to their own role-level permissions. A user in multiple groups receives the union of all group permissions.

Endpoints

Method	Path	Description	Required Permission
GET	/groups	List all groups in the tenant	iam:read
GET	/groups/{id}	Get a single group with its members	iam:read
POST	/groups	Create a new group	iam:write
PUT	/groups/{id}	Update group name, description, role, or members	iam:write
DELETE	/groups/{id}	Delete a group (members retain their individual roles)	iam:admin

Group Object

Group Response Object

{
  "id": "grp_data_team",
  "name": "Data Team",
  "description": "Analytics and data engineering team with read access to all FinOps modules",
  "role_id": "role_analyst",
  "member_count": 12,
  "created_at": "2024-01-10T08:00:00Z"
}

Group Fields Reference

Field	Type	Description
id	string	Unique identifier for the group
name	string	Human-readable group name shown in the IAM UI
description	string	Optional description of the group's purpose
role_id	string	The role applied to all members of this group. All members inherit this role's permission set.
member_count	integer	Read-only count of active users in the group

Permission Inheritance

Groups aggregate users under a common role. The group's role_id defines the permission set applied to all members:

All members of a group inherit the group's role permissions.
A user in multiple groups receives the union of all group permissions — the most permissive set wins.
User-level permission overrides always take precedence over group permissions.

Deleting a Group

Deleting a group removes the group membership from all members but does not delete the users or change their individual role assignments. Users lose the group's permissions but retain permissions from their own role and other group memberships.