Groups

Manage user groups, membership, and application assignments.

GET/api/v1/groupsList organization groupsBearer Token▾

Returns a paginated list of groups belonging to the current organization. Supports filtering by search term.

Parameters

Name	Type	Required	Description
`search`	string	Optional	Search term to filter groups by name.e.g. `engineering`
`page`	number	Optional	Page number for pagination (1-indexed).e.g. `1`
`limit`	number	Optional	Number of results per page.e.g. `20`

Response Fields

Name	Type	Required	Description
`data`	Group[]	Optional	Array of group records for the current page.
`total`	number	Optional	Total number of groups matching the query.
`page`	number	Optional	Current page number.
`limit`	number	Optional	Number of results per page.

Response Example

{
  "data": [
    {
      "id": "grp_01hx9z1q2w3e4r5t6y7u",
      "name": "Engineering",
      "description": "Core engineering team",
      "memberCount": 12,
      "createdAt": "2024-01-10T08:00:00Z"
    }
  ],
  "total": 8,
  "page": 1,
  "limit": 20
}

Code Examples

curl -X GET "https://api.sutraid.com/api/v1/groups?page=1&limit=20" \
  -H "Authorization: Bearer <your_token>" \
  -H "x-org-id: <your_org_id>"

POST/api/v1/groupsCreate groupBearer Token▾

Creates a new group within the organization. Groups can be used to manage bulk access to applications.

Request Body

Name	Type	Required	Description
`name`	string	Required	Name of the group. Maximum 100 characters.e.g. `Engineering`
`description`	string	Optional	Optional description of the group. Maximum 500 characters.e.g. `Core engineering team with access to all developer tooling.`

Response Fields

Name	Type	Required	Description
`id`	string	Optional	Unique identifier of the created group.
`name`	string	Optional	Name of the group.
`description`	string	Optional	Description of the group.
`memberCount`	number	Optional	Number of members in the group.
`createdAt`	string	Optional	ISO 8601 creation timestamp.

Response Example

{
  "id": "grp_01hx9z1q2w3e4r5t6y7u",
  "name": "Engineering",
  "description": "Core engineering team with access to all developer tooling.",
  "memberCount": 0,
  "createdAt": "2024-06-01T12:00:00Z"
}

Code Examples

curl -X POST "https://api.sutraid.com/api/v1/groups" \
  -H "Authorization: Bearer <your_token>" \
  -H "x-org-id: <your_org_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Engineering",
    "description": "Core engineering team with access to all developer tooling."
  }'

PUT/api/v1/groups/:idUpdate groupBearer Token▾

Updates the name or description of an existing group.

Parameters

Name	Type	Required	Description
`id`	string (UUID)	Required	Unique identifier of the group to update.e.g. `grp_01hx9z1q2w3e4r5t6y7u`

Request Body

Name	Type	Required	Description
`name`	string	Optional	Updated group name. Maximum 100 characters.e.g. `Platform Engineering`
`description`	string	Optional	Updated group description. Maximum 500 characters.e.g. `Platform and infrastructure team.`

Response Fields

Name	Type	Required	Description
`id`	string	Optional	Group identifier.
`name`	string	Optional	Updated group name.
`description`	string	Optional	Updated group description.
`updatedAt`	string	Optional	ISO 8601 timestamp of last update.

Response Example

{
  "id": "grp_01hx9z1q2w3e4r5t6y7u",
  "name": "Platform Engineering",
  "description": "Platform and infrastructure team.",
  "updatedAt": "2024-06-01T15:00:00Z"
}

Code Examples

curl -X PUT "https://api.sutraid.com/api/v1/groups/grp_01hx9z1q2w3e4r5t6y7u" \
  -H "Authorization: Bearer <your_token>" \
  -H "x-org-id: <your_org_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Platform Engineering",
    "description": "Platform and infrastructure team."
  }'

DELETE/api/v1/groups/:idDelete groupBearer Token▾

Permanently deletes a group from the organization. All user memberships and application assignments for this group are also removed.

Parameters

Name	Type	Required	Description
`id`	string (UUID)	Required	Unique identifier of the group to delete.e.g. `grp_01hx9z1q2w3e4r5t6y7u`

Response Fields

Name	Type	Required	Description
`message`	string	Optional	Confirmation message.e.g. `Group deleted`

Response Example

{
  "message": "Group deleted"
}

Code Examples

curl -X DELETE "https://api.sutraid.com/api/v1/groups/grp_01hx9z1q2w3e4r5t6y7u" \
  -H "Authorization: Bearer <your_token>" \
  -H "x-org-id: <your_org_id>"

PUT/api/v1/groups/:id/usersSet group membersBearer Token▾

Replaces the entire set of members for a group with the provided list of user IDs. Any users not in the list will be removed from the group.

Parameters

Name	Type	Required	Description
`id`	string (UUID)	Required	Unique identifier of the group.e.g. `grp_01hx9z1q2w3e4r5t6y7u`

Request Body

Name	Type	Required	Description
`userIds`	string[]	Required	Array of user UUIDs to set as group members. Replaces the existing membership list entirely.e.g. `["usr_01hx9z1q2w3e4r5t6y7u", "usr_02hx9z1q2w3e4r5t6y7v"]`

Response Fields

Name	Type	Required	Description
`id`	string	Optional	Group identifier.
`users`	User[]	Optional	Updated list of users in the group.

Response Example

{
  "id": "grp_01hx9z1q2w3e4r5t6y7u",
  "users": [
    {
      "id": "usr_01hx9z1q2w3e4r5t6y7u",
      "email": "alice@example.com",
      "firstName": "Alice",
      "lastName": "Nguyen"
    },
    {
      "id": "usr_02hx9z1q2w3e4r5t6y7v",
      "email": "bob@example.com",
      "firstName": "Bob",
      "lastName": "Smith"
    }
  ]
}

Code Examples

curl -X PUT "https://api.sutraid.com/api/v1/groups/grp_01hx9z1q2w3e4r5t6y7u/users" \
  -H "Authorization: Bearer <your_token>" \
  -H "x-org-id: <your_org_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "userIds": [
      "usr_01hx9z1q2w3e4r5t6y7u",
      "usr_02hx9z1q2w3e4r5t6y7v"
    ]
  }'

PUT/api/v1/groups/:id/applicationsSet group applicationsBearer Token▾

Replaces all application assignments for a group with the provided list of application IDs. All members of the group will inherit access to the specified applications.

Parameters

Name	Type	Required	Description
`id`	string (UUID)	Required	Unique identifier of the group.e.g. `grp_01hx9z1q2w3e4r5t6y7u`

Request Body

Name	Type	Required	Description
`applicationIds`	string[]	Required	Array of application UUIDs to assign to the group. Replaces the existing application list entirely.e.g. `["app_01hx9z1q2w3e4r5t6y7u", "app_02hx9z1q2w3e4r5t6y7v"]`

Response Fields

Name	Type	Required	Description
`id`	string	Optional	Group identifier.
`applications`	Application[]	Optional	Updated list of applications assigned to the group.

Response Example

{
  "id": "grp_01hx9z1q2w3e4r5t6y7u",
  "applications": [
    {
      "id": "app_01hx9z1q2w3e4r5t6y7u",
      "name": "Acme CRM"
    },
    {
      "id": "app_02hx9z1q2w3e4r5t6y7v",
      "name": "Internal Dashboard"
    }
  ]
}

Code Examples

curl -X PUT "https://api.sutraid.com/api/v1/groups/grp_01hx9z1q2w3e4r5t6y7u/applications" \
  -H "Authorization: Bearer <your_token>" \
  -H "x-org-id: <your_org_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "applicationIds": [
      "app_01hx9z1q2w3e4r5t6y7u",
      "app_02hx9z1q2w3e4r5t6y7v"
    ]
  }'