Access Control Groups
An access control group defines a group of access permissions on resources.
Endpoints
Get access control groups
Endpoint
get /accessControlGroups
Description
Get a list of access control groups. Either the projectId, readableByUserID, or memberUserId must be specified. When the search parameter is used, only groups that name or description matching exactly or partially one of the phrases will be returned.
Query Parameters
projectId
integer
Return access control groups of the specified project. If the request is made by a user, the user must have read permission for all access control group.
readableByUserID
integer
Return access control groups that a particular user can read. If the request is made by a user, readableByUserID must be the ID of the user, or the user must have manage permissions for all resources.
memberUserId
integer
Return access control groups that a particular user belongs to. If the request is made by a user, memberUserId must be the ID of the user, or the user must have manage permissions for all resources.
search
string
Search for groups by keywords. The search string may contain multiple phrases separated by whitespaces.
skip
integer
Number of access control groups to skip over.
limit
integer
Maximum number of access control groups to return.
Default value is
25
Minimum value is
1
Request Headers What's this?
Authorization
required
Must contain a user or project API key with "Admin" privileges.
Response
- 200Successful retrieval of list of access control groups.
- 401Authorization is required to access this resource.
- 403Request failed because of denied permission.
- 500An unexpected error has occurred.
- 503The service is temporarily unavailable.
Response Body Sample
[
{
"id": 1,
"projectId": 10,
"name": "Customer Support",
"description": "A group to access all devices in the project"
},
{
"id": 2,
"projectId": 10,
"name": "Customer Support Admin",
"description": "A group to manage customer support user accounts"
}
]
Create an access control group
Endpoint
post /accessControlGroups
Description
Create an access control group. If the request is made by a user, the user must have permission to create access control group.
Request Headers What's this?
Authorization
required
Must contain a user or project API key with "Admin" privileges.
Request Body
projectId
number
required
The project that this access control group belongs to.
name
string
required
The display name of the group.
description
string
required
The description of the group.
Response
- 201Successfully created a new access control group.
- 401Authorization is required to access this resource.
- 403Request failed because of invalid data or denied permission.
- 500An unexpected error has occurred.
- 503The service is temporarily unavailable.
Request Body Sample
{
"projectId": 10,
"name": "Customer Support",
"description": "A group to access all devices in the project"
}
Response Body Sample
{
"id": 1,
"projectId": 10,
"name": "Customer Support",
"description": "A group to access all devices in the project"
}
Get an access control group
Endpoint
get /accessControlGroups/{accessControlGroupId}
Description
Return the access control group with the specified ID.
Path Parameters
accessControlGroupId
integer
required
The unique ID for a specified access control group.
Request Headers What's this?
Authorization
required
Must contain a user or project API key.
Response
- 200Successfully retrieved access control group with specified ID.
- 401Authorization is required to access this resource.
- 403Request failed because of denied permission.
- 404The requested accessControlGroup does not exist or is not accessible.
- 500An unexpected error has occurred.
- 503The service is temporarily unavailable.
Response Body Sample
{
"id": 1,
"projectId": 10,
"name": "Customer Support",
"description": "A group to access all devices in the project"
}
Update an access control group
Endpoint
patch /accessControlGroups/{accessControlGroupId}
Description
Update the access control group with the specified ID. Only the name
and description
field can be changed.
Path Parameters
accessControlGroupId
integer
required
The unique ID for a specified access control group.
Request Headers What's this?
Authorization
required
Must contain a user API key or a project API key with "Admin" privileges.
Request Body
name
string
The new name.
description
string
The new description.
Response
- 204Successfully updated access control group with specified ID. There is no return body.
- 401Authorization is required to access this resource.
- 403Request failed because of invalid data or denied permission.
- 404The requested accessControlGroup does not exist or is not accessible.
- 500An unexpected error has occurred.
- 503The service is temporarily unavailable.
Request Body Sample
{
"name": "Customer Support",
"description": "A group to access all devices in the project"
}
Delete an access control group
Endpoint
delete /accessControlGroups/{accessControlGroupId}
Description
Delete the access control group with the specified ID.
Path Parameters
accessControlGroupId
integer
required
The unique ID for a specified access control group.
Request Headers What's this?
Authorization
required
Must contain a user API key or a project API key with "Admin" privileges.
Response
- 204Successfully deleted access control group with the specified ID. There is no return body.
- 401Authorization is required to access this resource.
- 403Request failed because of invalid data or denied permission.
- 404The required accessControlGroup does not exist or is not accessible.
- 409The accessControlGroup cannot be deleted because it is being used by another part of the system.
- 500An unexpected error has occurred.
- 503The service is temporarily unavailable.
Manage the membership of group
Endpoint
post /accessControlGroups/{accessControlGroupId}/membership
Description
Manage the relationship between the group and the principal.
The interface is non-RESTful. The request body must contain an action
in the payload.
The caller must have update permissions on both the target access control group and the target principal.
Path Parameters
accessControlGroupId
integer
required
The unique ID for a specified access control group.
Request Headers What's this?
Authorization
required
Must contain a user or project API key with "Admin" privileges.
Request Body
action
string
required
add
action adds the principal to the group.remove
action removes the principal from the group.principalType
string
required
Must be
user
.principalId
number
required
The ID of a principal (i.e., userId).
Response
- 200Successfully updated the membership.
- 401Authorization is required to access this resource.
- 403Request failed because of invalid data or denied permission.
- 500An unexpected error has occurred.
- 503The service is temporarily unavailable.
Request Body Sample
{
"action": "add",
"principalType": "user",
"principalId": 123
}
Response Body Sample
{
"action": "add",
"principalType": "user",
"principalId": 123
}