Groups

A group is a named bundle of users inside one workspace. Attach an IAM policy to a group, add a handful of users to it, and they all inherit the policy — the same pattern AWS IAM groups follow.

Groups have no permissions of their own; they exist purely as a target for policy attachments. A user can belong to many groups; effective permissions are the union of:

1. Policies attached directly to the user.
2. Policies attached to every group the user is a member of.

All endpoints require a bearer admin JWT — see Authentication.

Endpoints

Method	Path	Purpose
POST	/v1/iam/groups	Create a group
GET	/v1/iam/groups	List groups in the active workspace
GET	/v1/iam/groups/:id	Retrieve one group with its members
DELETE	/v1/iam/groups/:id	Delete a group
POST	/v1/iam/groups/:id/members	Add a user to the group
DELETE	/v1/iam/groups/:id/members/:userId	Remove a user from the group

Only owner and admin can mutate. Members can GET but not modify.

Create a group

POST /v1/iam/groups

Request body

Field	Type	Required	Description
name	string (1–120)	yes	Display name. Conventionally short and capitalised (Engineering, Finance, Read-only).
description	string (≤500)	no	Free-form description shown in the dashboard.

Response — 201 Created

{
  "data": {
    "id": "grp_01KPG…",
    "accountId": "acc_01KPG…",
    "name": "Engineering",
    "description": "Engineering team — full access to dev resources, read-only on billing.",
    "createdAt": "2026-05-12T23:30:00.000Z"
  }
}

List groups

GET /v1/iam/groups

Returns groups in the active workspace, newest first. Each row includes a _count.members field so the dashboard can render member counts without a second round-trip.

{
  "data": [
    {
      "id": "grp_01KPG…",
      "name": "Engineering",
      "description": "…",
      "createdAt": "2026-05-12T23:30:00.000Z",
      "_count": { "members": 7 }
    }
  ]
}

Retrieve a group

GET /v1/iam/groups/:id

Returns the full group with member rows expanded.

{
  "data": {
    "id": "grp_01KPG…",
    "name": "Engineering",
    "members": [
      {
        "id": "gmb_01KPG…",
        "userId": "usr_01KPG…",
        "user": {
          "id": "usr_01KPG…",
          "email": "adi@forjio.com",
          "name": "Adhya Pranata Sakti"
        }
      }
    ]
  }
}

Delete a group

DELETE /v1/iam/groups/:id

Hard-deletes the group. Member rows and policy attachments cascade-delete; users keep any policies attached to them directly.

204 No Content.

Add a member

POST /v1/iam/groups/:id/members

Request body

Field	Type	Description
userId	string (usr_…)	The user to add. Must be a member of the active workspace.

201 Created returns the membership row. 409 if the user is already in the group.

Remove a member

DELETE /v1/iam/groups/:id/members/:userId

Removes a user from the group. Their direct policy attachments and other group memberships are untouched.

204 No Content.

The group object

Field	Type	Description
id	string (grp_…)	Stable group ID.
accountId	string (acc_…)	Owning workspace.
name	string	Display name. Must be unique per workspace.
description	string | null	Operator note.
createdAt	ISO 8601
_count.members	integer	Member count (list response only).
members	array	Expanded member rows (detail response only).

Common patterns

• Engineering / Finance / Operations. Three groups by function, each attached to one or two policies. Easiest model.
• Read-only. One group attached to HuudisReadOnly (a system policy). Add anyone you want to grant audit-only access.
• MFA-required. Pair with a policy that denies huudis:* when forjio:MfaPresent is false. Members of this group are forced to enrol MFA before they can do anything.

Groups are intentionally lightweight — there are no nested groups, no auto-membership rules, no JIT provisioning. Keep the count low (single digits) and rely on direct user-policy attachments for edge cases.

Events

No events for group CRUD. Audit-log entries (iam.group.created, iam.group.deleted, iam.group.member_added, iam.group.member_removed) cover the same operations.

Next

• Policies — the documents you attach to groups.
• Attachments — the join between a policy and a group/user/role.
• Users — the principals that get added to groups.