Roles¶

On this page, you will find descriptions of the API methods intended for working with roles for technicians from the Team section.

Role Management¶

Role List¶

Retrieve a list of all roles available for configuring access permissions using the /team/role/list endpoint.

Request:

HTTPcURL

GET /v1/team/role/list
  ?search=<string>
  &type=<string>
  &offset=<number>
  &limit=<number>
Host: https://api.getscreen.me
X-Api-Key: YOUR_API_KEY

curl -G "https://api.getscreen.me/v1/team/role/list" \
  --data-urlencode "search=<string>" \
  --data-urlencode "type=<string>" \
  --data-urlencode "offset=<number>" \
  --data-urlencode "limit=<number>" \
  -H "X-Api-Key: YOUR_API_KEY"

Parameter	Type	Description
`search`	`string`	Case-insensitive filter by role name.
`type`	`string`	Role type. See the available values in the reference below.
`offset`	`number`	Offset for the first item in the list. Default value: `0`
`limit`	`number`	Number of items in the list. Default value: `20`; maximum value: `100`

Response:

Example Response

Response Data

{
    "data": [ {
        "id": 1001,
        "name": "Auditor",
        "type": "agent",
        "permission": [
            "agent_connect",
            "agent_control"
        ],
        "default": false
    } ]
}

Name	Type	Description
`id`	`number`	Internal system identifier of the role.
`name`	`string`	Role name.
`type`	`string`	Role type. See the available values in the reference below.
`permission[]`	`array`	List of permissions. See the available values in the reference below.
`default`	`boolean`	Indicates whether this is a system role.

Role Info¶

You can retrieve information about a specific role using the team/role/info method.

Request:

HTTPcURL

GET /v1/team/role/info
  ?id=<number>
Host: https://api.getscreen.me
X-Api-Key: YOUR_API_KEY

curl -G "https://api.getscreen.me/v1/team/role/info" \
  --data-urlencode "id=<number>" \
  -H "X-Api-Key: YOUR_API_KEY" \

Parameter	Type	Value
`id`	`number`	Internal system role ID

Response:

Example Response

Response Data

{
    "data": {
        "id": 1000341,
        "name": "Notification",
        "type": "agent",
        "description": "Allows you to manage devices and receive notifications from them.",
        "default": false,
        "permission": [
            "agent_get_info",
            "agent_notification"
        ]
    }
}

Name	Type	Description
`id`	`number`	Internal system identifier of the role.
`name`	`string`	Role name.
`type`	`string`	Role type. See the available values in the reference below.
`description`	`string`	Brief description of the role.
`default`	`boolean`	Indicates whether this is a system role.
`permission[]`	`array`	List of permissions. See the available values in the reference below.

Create Role¶

Create a custom role using the /team/role/create endpoint.

Request:

HTTPcURL

POST /v1/team/role/create
Host: https://api.getscreen.me
X-Api-Key: YOUR_API_KEY

{
  "name": <string>,
  "description": <string>,
  "type": <string>,
  "permission": [ <string>, ... ]
}

curl -X POST "https://api.getscreen.me/v1/team/role/create" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "name": <string>,
    "description": <string>,
    "type": <string>,
    "permission": [ <string>, ... ]
  }'

Parameter	Type	Description
`name`	`string`	Name of the new role.
`description`	`string`	Role description.
`type`	`string`	Role type. See the available values in the reference below.
`permission`	`array`	List of permissions. See the available values in the reference below.

Response:

Example Response

Response Data

{
    "status": 0
}

Name	Type	Description
`id`	`number`	Internal system identifier of the created role.
`status`	`number`	Result status. Possible values: `0` — Role created successfully. `1` — Invalid request data. `6` — Insufficient permissions.

Edit Role¶

Update an existing custom role using the /team/role/edit endpoint.

Request:

HTTPcURL

POST /v1/team/role/edit
Host: https://api.getscreen.me
X-Api-Key: YOUR_API_KEY

{
  "id": <number>,
  "name": <string>,
  "description": <string>,
  "permission": [ <string>, ... ]
}

curl -X POST "https://api.getscreen.me/v1/team/role/edit" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "id": <number>,
    "name": <string>,
    "description": <string>,
    "permission": [ <string>, ... ]
  }'

Parameter	Type	Description
`id`	`number`	Identifier of the role to update.
`name`	`string`	New role name.
`description`	`string`	Role description.
`permission`	`array`	List of permissions. See the available values in the reference below.

Response:

Example Response

Response Data

{
    "status": 0
}

Name	Type	Description
`status`	`number`	Result status. Possible values: `0` — Role updated successfully. `1` — Invalid request data. `6` — Insufficient permissions.

Remove Role¶

Delete an existing custom role using the /team/role/remove endpoint.

Request:

HTTPcURL

POST /v1/team/role/remove
Host: https://api.getscreen.me
X-Api-Key: YOUR_API_KEY

{
  "id": <number>
}

curl -X POST "https://api.getscreen.me/v1/team/role/remove" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "id": <number>
  }'

Parameter	Type	Description
`id`	`number`	Identifier of the custom role to delete.

Response:

Example Response

Response Data

{
    "status": 0
}

Name	Type	Description
`status`	`number`	Result status. Possible values: `0` — Role removed successfully. `1` — Invalid request data. `6` — Insufficient permissions.

Role Assignment¶

Roles are grouped into three categories based on their purpose. The available permissions depend on the role type.

Name	Identifier	Purpose
Devices and Groups	`agent` or `group`	Manage devices in Permanent Access.
Invitations	`quick_support`	Manage invitations in Quick Support.
Administration	`team`	Administer the Team account and its settings.

Role Permissions¶

Permissions define the functions allowed for a specific role. They depend on the chosen purpose.

Devices and GroupsInvitationsAdministration

Name	ID	Description
Actions		Available connection modes to the device
Screen View	`agent_connect`	Allows connecting to the device’s screen in view-only mode
Screen Control	`agent_control`	Allows controlling the device’s screen using the mouse and keyboard
File Manager	`agent_file_transfer`	Allows access to the device’s file system
Terminal Mode	`agent_terminal_mode`	Allows terminal-mode access to the device
Wake Up	`agent_wake_on_lan`	Allows waking the device via Wake-on-LAN
Reboot	`agent_reboot`	Allows rebooting the remote device
Lock/Unlock	`agent_lock_screen`	Allows locking the remote OS account
Session options		Features available during a remote session
No Confirmation	`agent_no_confirm`	Allows connecting without requesting confirmation from the remote user Works only when connecting to devices for which connection approval requirements are configured through group settings.
Calls	`agent_audio_calls`	Allows making calls
Black Screen and Input Lock	`agent_lock_input`	Allows blocking the screen and input devices
Chat	`agent_chat`	Allows sending text messages
Sync Clipboard	`agent_clipboard`	Allows syncing the clipboard
Other options		Other system functions applicable to devices
Screen Preview	`agent_preview`	Allows screen video preview in the device list
Connection History	`agent_sessions`	Allows access to connection history
Software Inventory	`agent_program_list`	Allows access to installed software information
Modify Notifications	`agent_notification`	Allows managing notifications
Video Recording Delete	`agent_remove_video`	Allows deleting video recordings
Device Modify	`agent_change_settings`	Allows editing device properties
Device Delete	`agent_logout`	Allows deleting devices

Name	ID	Description
Access to Invitations		Which invitations are accessible
Own Invitations	`quick_support_admin`	Allows access only to one’s own invitations
All Invitations	`quick_support_technical`	Allows access to all team invitations
Actions		Available connection modes
Screen View	`agent_connect`	Allows connecting in screen view mode
Screen Control	`agent_control`	Allows controlling the screen using mouse and keyboard
File Manager	`agent_file_transfer`	Allows access to the file system
Terminal Mode	`agent_terminal_mode`	Allows terminal-mode connection
Session options		Features available during a connection
Calls	`agent_audio_calls`	Allows making calls
Chat	`agent_chat`	Allows sending text messages
Reboot	`agent_reboot`	Allows rebooting the device
Installation Request	`agent_app_install_request`	Allows sending a request to install the agent application application
Sync Clipboard	`agent_clipboard`	Allows syncing the clipboard
Other options		Other functions
Screen Preview	`agent_preview`	Allows screen video preview in the list
Video Recording Delete	`agent_remove_video`	Allows deleting session recordings

Name	ID	Description
Administrator functions		Administration features
Audit Log	`team_security_log_admin`	Allows access to team-wide audit logs
Technicians and Team Settings	`team_user_admin`	Allows managing technicians and team settings
Branding Settings	`team_brand_admin`	Allows access to branding settings
Billing Settings	`team_billing_admin`	Allows managing billing
API Settings	`team_api_key`	Allows managing API keys.
Other		Other features
Permanent Access	`team_permanent_access`	Grants access to the Permanent Access section. Normally this section appears if the user has rights to at least one device or group, but in some cases it may not be visible. This permission explicitly enables access to this section, for example to add a new device.