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
}