Groups - FullStackHero .NET Starter Kit

Overview

The Groups API provides endpoints for managing user groups. Groups allow you to organize users and assign roles at the group level, making it easier to manage permissions for multiple users.

List Groups

Retrieve all groups for the current tenant with optional search filtering.

curl -X GET "https://api.example.com/api/v1/identity/groups?search=admin" \
  -H "Authorization: Bearer {access_token}"

HTTP Request

GET /api/v1/identity/groups

Authorization

Requires Permissions.Groups.View permission.

Query Parameters

string

Optional search term to filter groups by name or description

Response

Returns an array of GroupDto objects.

guid

Group’s unique identifier

name

string

Group name

description

string

Group description (optional)

isDefault

boolean

Whether this is a default group (new users are automatically added)

isSystemGroup

boolean

Whether this is a system-managed group (cannot be deleted)

memberCount

integer

Number of users in the group

roleIds

array<string>

Array of role IDs assigned to the group

roleNames

array<string>

Array of role names assigned to the group

createdAt

datetime

Timestamp when the group was created

Response Example

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Administrators",
    "description": "System administrators group",
    "isDefault": false,
    "isSystemGroup": true,
    "memberCount": 5,
    "roleIds": ["admin-role-id"],
    "roleNames": ["Administrator"],
    "createdAt": "2026-01-15T10:30:00Z"
  },
  {
    "id": "7b9c3d2a-8e5f-4a6b-9c7d-1e2f3a4b5c6d",
    "name": "Managers",
    "description": "Department managers",
    "isDefault": false,
    "isSystemGroup": false,
    "memberCount": 12,
    "roleIds": ["manager-role-id"],
    "roleNames": ["Manager"],
    "createdAt": "2026-02-01T14:20:00Z"
  }
]

Get Group by ID

Retrieve a specific group by its unique identifier.

curl -X GET https://api.example.com/api/v1/identity/groups/{groupId} \
  -H "Authorization: Bearer {access_token}"

HTTP Request

GET /api/v1/identity/groups/{id}

Authorization

Requires Permissions.Groups.View permission.

Path Parameters

guid

required

The unique identifier of the group

Response

Returns a GroupDto object with group details.

Create Group

Create a new group with optional role assignments.

curl -X POST https://api.example.com/api/v1/identity/groups \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Engineering Team",
    "description": "Software engineering department",
    "isDefault": false,
    "roleIds": ["developer-role-id", "viewer-role-id"]
  }'

HTTP Request

POST /api/v1/identity/groups

Authorization

Requires Permissions.Groups.Create permission.

Request Body

name

string

required

Group name (must be unique within the tenant)

description

string

Group description (optional)

isDefault

boolean

required

Whether new users should be automatically added to this group

roleIds

array<string>

Array of role IDs to assign to the group (optional)

Response

Returns the created GroupDto object.

Response Example

{
  "id": "9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
  "name": "Engineering Team",
  "description": "Software engineering department",
  "isDefault": false,
  "isSystemGroup": false,
  "memberCount": 0,
  "roleIds": ["developer-role-id", "viewer-role-id"],
  "roleNames": ["Developer", "Viewer"],
  "createdAt": "2026-03-06T15:45:00Z"
}

Update Group

Update an existing group’s details and role assignments.

curl -X PUT https://api.example.com/api/v1/identity/groups/{groupId} \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Engineering Team",
    "description": "Updated description",
    "isDefault": true,
    "roleIds": ["developer-role-id"]
  }'

HTTP Request

PUT /api/v1/identity/groups/{id}

Authorization

Requires Permissions.Groups.Update permission.

Path Parameters

guid

required

The unique identifier of the group to update

Request Body

Same as Create Group request body.

Response

Returns 200 OK on successful update.

Delete Group

Soft delete a group. System groups cannot be deleted.

curl -X DELETE https://api.example.com/api/v1/identity/groups/{groupId} \
  -H "Authorization: Bearer {access_token}"

HTTP Request

DELETE /api/v1/identity/groups/{id}

Authorization

Requires Permissions.Groups.Delete permission.

Path Parameters

guid

required

The unique identifier of the group to delete

Response

Returns 200 OK on successful deletion.

Notes

System groups (where isSystemGroup = true) cannot be deleted
Deleting a group does not delete its members, only their group membership
Users in the deleted group will lose permissions derived from group role assignments

Get Group Members

Retrieve all members of a specific group.

curl -X GET https://api.example.com/api/v1/identity/groups/{groupId}/members \
  -H "Authorization: Bearer {access_token}"

HTTP Request

GET /api/v1/identity/groups/{id}/members

Authorization

Requires Permissions.Groups.View permission.

Path Parameters

guid

required

The unique identifier of the group

Response

Returns an array of GroupMemberDto objects containing user information.

Add Users to Group

Add one or more users to a group.

curl -X POST https://api.example.com/api/v1/identity/groups/{groupId}/members \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "userIds": [
      "user-id-1",
      "user-id-2",
      "user-id-3"
    ]
  }'

HTTP Request

POST /api/v1/identity/groups/{groupId}/members

Authorization

Requires Permissions.Groups.ManageMembers permission.

Path Parameters

groupId

guid

required

The unique identifier of the group

Request Body

userIds

array<string>

required

Array of user IDs to add to the group

Response

Returns information about the operation, including:

Count of users successfully added
List of users already in the group (if any)

Remove User from Group

Remove a specific user from a group.

curl -X DELETE https://api.example.com/api/v1/identity/groups/{groupId}/members/{userId} \
  -H "Authorization: Bearer {access_token}"

HTTP Request

DELETE /api/v1/identity/groups/{groupId}/members/{userId}

Authorization

Requires Permissions.Groups.ManageMembers permission.

Path Parameters

groupId

guid

required

The unique identifier of the group

userId

string

required

The unique identifier of the user to remove

Response

Returns 200 OK on successful removal.

Get User Groups

Retrieve all groups that a specific user belongs to.

curl -X GET https://api.example.com/api/v1/identity/users/{userId}/groups \
  -H "Authorization: Bearer {access_token}"

HTTP Request

GET /api/v1/identity/users/{userId}/groups

Authorization

Requires Permissions.Users.View permission.

Path Parameters

userId

string

required

The unique identifier of the user

Response

Returns an array of GroupDto objects representing the user’s group memberships.

Group-Based Permissions

Groups provide an efficient way to manage permissions at scale:

Role Assignment: Roles are assigned to groups, not individual users
Permission Inheritance: Users inherit all permissions from their group’s roles
Centralized Management: Update permissions for multiple users by modifying group roles
Default Groups: Automatically add new users to specific groups

Example Workflow

Best Practices

Use groups to organize users by department, project, or function for easier permission management.

System groups are protected and cannot be deleted. Use them for critical organizational structures.

Removing a user from a group immediately revokes all permissions derived from that group’s roles.

Identity API

Multitenancy API

Auditing API

​Overview

​List Groups

​HTTP Request

​Authorization

​Query Parameters

​Response

​Response Example

​Get Group by ID

​HTTP Request

​Authorization

​Path Parameters

​Response

​Create Group

​HTTP Request

​Authorization

​Request Body

​Response

​Response Example

​Update Group

​HTTP Request

​Authorization

​Path Parameters

​Request Body

​Response

​Delete Group

​HTTP Request

​Authorization

​Path Parameters

​Response

​Notes

​Get Group Members

​HTTP Request

​Authorization

​Path Parameters

​Response

​Add Users to Group

​HTTP Request

​Authorization

​Path Parameters

​Request Body

​Response

​Remove User from Group

​HTTP Request

​Authorization

​Path Parameters

​Response

​Get User Groups

​HTTP Request

​Authorization

​Path Parameters

​Response

​Group-Based Permissions

​Example Workflow

​Best Practices

Build docs developers (and LLMs) love

Overview

List Groups

HTTP Request

Authorization

Query Parameters

Response

Response Example

Get Group by ID

HTTP Request

Authorization

Path Parameters

Response

Create Group

HTTP Request

Authorization

Request Body

Response

Response Example

Update Group

HTTP Request

Authorization

Path Parameters

Request Body

Response

Delete Group

HTTP Request

Authorization

Path Parameters

Response

Notes

Get Group Members

HTTP Request

Authorization

Path Parameters

Response

Add Users to Group

HTTP Request

Authorization

Path Parameters

Request Body

Response

Remove User from Group

HTTP Request

Authorization

Path Parameters

Response

Get User Groups

HTTP Request

Authorization

Path Parameters

Response

Group-Based Permissions

Example Workflow

Best Practices