Group Collection

Location /api/apps/{appID}/groups
The collection of groups that belongs to the accessed application.

Request Headers (Applies to all methods)

Authorization
header
Required: Yes

GET

/api/apps/{appID}/groups

Description

Get a list of groups.

You can filter the list by the membership or by ownership.

  • By setting the "is_member" parameter, you can retrieve a list of groups in which the specified user is a member.
  • By setting the "owner" parameter, you can retrieve a list of groups in which the specified user is an owner.

Security

An anonymous access is not allowed for this method.

Content-Type application/json

Headers
Name Required? type Description
Authorization Yes string Authorization header. OAuth2 Bearer token
Params
Name Required? Type Description
is_member No string A userID for filtering (by member)
owner No string A userID for filtering (by owner)
Responses
200

Content-Type application/vnd.kii.GroupsRetrievalResponse+json

The list of groups has been retrieved successfully.
Contents
Name Type Description
groups GroupRetrievalResponse
groupID string The ID of the group.
name string The name of the group.
owner string The userID of the group owner.
404

Content-Type application/vnd.kii.UserNotFoundException+json

The user was not found.
Contents
Name Type Description
errorCode string Error code "USER_NOT_FOUND".
message string The error message.
field string The field used for searching the user. This can be the userID or address field.
value string The field value used for searching the user.
appID string The ID of the application.
401

Content-Type application/vnd.kii.UnauthorizedAccessException+json

Not authorized to query for groups.
Contents
Name Type Description
errorCode string Error code "UNAUTHORIZED".
message string The error message.
authenticatedAppID string The authenticated appID.
authenticatedPrincipalID string The authenticated principal ID (userID or thingID).

POST

/api/apps/{appID}/groups

Description

Create a new group.

The group owner will be added as a group member by default.

Security

An anonymous and thing access is not allowed for this method. If accessing as the administrator, an owner is not required.

Content-Type application/vnd.kii.GroupCreationRequest+json

All the required data for creating the group.

Headers
Name Required? type Description
Authorization Yes string Authorization header. OAuth2 Bearer token
Params
Name Required? Type Description
name Yes string The name of the group.
owner string The userID of the group owner.
members string A collection of the group member's userIDs.
Sample Request 
{
  "name": "[string]",
  "owner": "[string]",
  "members": "[string]"
}
Responses
201

Content-Type application/vnd.kii.GroupCreationResponse+json

The group has been created successfully.
Headers
Name Type Description
Location string URI of the created group.
Contents
Name Type Description
groupID string The ID of the created group.
notFoundUsers string The collection of userIDs of the users who were not found and thus not added as the group members.
404

Content-Type application/vnd.kii.UserNotFoundException+json

The user was not found.
Contents
Name Type Description
errorCode string Error code "USER_NOT_FOUND".
message string The error message.
field string The field used for searching the user. This can be the userID or address field.
value string The field value used for searching the user.
appID string The ID of the application.
401

Content-Type application/vnd.kii.UnauthorizedAccessException+json

Not authorized to create the group.
Contents
Name Type Description
errorCode string Error code "UNAUTHORIZED".
message string The error message.
authenticatedAppID string The authenticated appID.
authenticatedPrincipalID string The authenticated principal ID (userID or thingID).