User Roles

Managing user permissions individually is time-consuming and inefficient. To simplify this, you can use our Roles API.

Roles allow you to define sets of permissions, such as viewing live and recorded video or fully managing users and devices, and assign these roles to users. This approach streamlines permission management and scales easily as your organization grows.

Before You Begin

1. Obtain an access token by following the Login Guide.
2. Retrieve the Base URL from API URLs.

With these prerequisites in place, you can quickly fetch existing roles, create new ones, and assign them to users.

Available endpoints:

• The /roles API is used for retrieving and managing roles.
• The /roleAssignments API is used to assign and manage roles.

1. Fetch All Roles

Retrieve a list of all the available roles within the account via /roles.
The list can be filtered using roleName__contains, include or limit the results with pageSize.

• roleName__contains (search on role name, or partial role name).
• include (e.g., permissions, notes, assignable, userCount).
• pageSize (default 100).

Example:

curl --location 'https://{BaseUrl}/api/v3.0/roles?include=permissions,notes,assignable,userCount&pageSize=100' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <access-token>'

Response:

{
  "nextPageToken": "",
  "prevPageToken": "",
  "totalSize": 1,
  "results": [
{
            "id": "8f2150c9-a44f-423f-958a-f2fa69681acc",
            "assignable": true,
            "userCount": 1,
            "name": "Default User",
            "notes": "Default user template",
            "permissions": {
                "viewLiveVideo": true,
                "viewHistoricVideo": true,
                "downloadVideo": true,
                "viewPreviewVideo": true
            },
            "default": false
        }
  ]
}

2. Create a New Role

Use /roles to create new roles and define what permissions should be granted within this role.
The parameters you can submit via this request are: name, notes, permissions and default.

• name: The role’s name (required).
• notes: Optional description.
• permissions: Define which actions this role can perform.
• default: Boolean to indicate if the role is default.

Example:

curl --location --request POST 'https://{BaseUrl}/api/v3.0/roles' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <access-token>' \
--data '{
  "name": "OperationsManager",
  "notes": "Role for operations management team",
  "default": false,
  "permissions": {
    "viewLiveVideo": true,
    "viewHistoricVideo": true,
    "downloadVideo": true,
    "editUsers": true,
    "editAllCameraSettings": true
  }
}'

3. Assign a Role to a User

Assign the newly created role to a user with /roleAssignments, eliminating the need to toggle each permission individually.
The parameters that are used to assign roles to users are userId, roleId.

• userId: The unique identifier of the user. Obtain via the /users endpoint.
• roleId: Can be obtained via /roles or via the response when a role is newly created.

Example:

curl --location --request POST 'https://{BaseUrl}/api/v3.0/roleAssignments:bulkcreate' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <access-token>' \
--data '[
  {"userId": "User123", "roleId": "8f2150c9-a44f-423f-958a-f2fa69681acc"}
]'

By using these endpoints, you can quickly view existing roles, create new ones aligned with your organizational structure, and assign them to users. This approach streamlines your permission management process, saves time, and ensures consistent access across your Eagle Eye Networks Video platform.