Config API Version 2 Roles

Introduction

Each User can be assigned one or more Roles. These Roles grant the User permission to view data or manage settings. Roles are effective for every organisation that the user has access to.

Certain roles are custom, and defined within the scope of a particular organisation. these roles may only be granted to users within that organisation.

Role Types

Roles may be one of the following types:

general which usually denotes a user’s primary role, e.g. “Administrator” or “User”.
feature which gives extra, feature specific permissions to a user, e.g. “Telephony Manager” or “Call Playback”.
custom which is a custom role definition for your orghanisation, with custom permissions.
legacy which is a general or feature role that is being phased out and may no longer be granted, only revoked.

List Available Roles

Shows defined roles for a particular organisation. These roles are available to be granted and/or revoked to users of this organisation.

Request:

GET /config/v2/organisations/{ORG SPECIFIER}/roles

URL Path Params

ORG SPECIFIER (int) - Organisation ID.

GET Params

filter (array) OPTIONAL - One or more filters.
sort (array) OPTIONAL - One or more sorting params.
limit (integer) OPTIONAL - limit on the result set.
offset (integer) OPTIONAL - offset of the result set.

Filter Types

The Roles list may be filtered by any of the returned fields.

Sort Types

The Roles list may be sorted by any of the returned fields.

Response:

Returns a list of Roles defined for use within the Organisation.

roleId (int) - ID of the defined Role.
roleType (string) - Type of the defined role, see Role Types.
roleName (string) - Name of the defined role.

{"roleId":"17","roleType":"general","roleName":"Administrator"}
{"roleId":"38","roleType":"general","roleName":"User"}
{"roleId":"67","roleType":"feature","roleName":"Call Playback"}

List Granted Roles by User

Shows roles assigned to a User.

Request:

GET /config/v2/users/{USER SPECIFIER}/roleMembers

URL Path Params

USER SPECIFIER (mixed) - User ID (int) or email address (string).

GET Params

filter (array) OPTIONAL - One or more filters.
sort (array) OPTIONAL - One or more sorting params.
limit (integer) OPTIONAL - limit on the result set.
offset (integer) OPTIONAL - offset of the result set.

Filter Types

The User Roles list may be filtered by any of the returned fields.

Sort Types

The User Roles list may be sorted by any of the returned fields.

Response:

Returns a list of Roles assigned to the User.

userId (int) - User ID.
username (string) - User’s login email address.
roleId (int) - ID of the assigned Role.
roleType (string) - type of the assigned Role, see Role Types.
roleName (string) - name of the assigned Role.

{"userId":"42","username":"some.person@example.com","roleId":"17","roleType":"general","roleName":"Administrator"}
{"userId":"59","username":"other.person@example.com","roleId":"38","roleType":"general","roleName":"User"}

Grant Roles

Assigns one or more Roles to a User.

Request:

POST /config/v2/users/{USER SPECIFIER}/roleMembers

URL Path Params

USER SPECIFIER (mixed) - User ID (int) or email address (string).

POST Params

roleId (array) - Array of Role IDs to assign to the User.

Response:

Returns the HTTP 204 (No Content) status code if update successful.

HTTP 204 - NO CONTENT

Revoke Roles

Removes one or more granted Roles from a User.

Request:

DELETE /config/v2/users/{USER SPECIFIER}/roleMembers

URL Path Params

USER SPECIFIER (mixed) - User ID (int) or email address (string).

POST Params

roleId (array) - Array of Role IDs to revoke from the User.

Response:

Returns the HTTP 204 (No Content) status code if update successful.

HTTP 204 - NO CONTENT