Docs

Appearance

Open console

Reference

Roles

REST API reference for Roles: manage the roles of a user account. 7 operations.

Reference4 min read

For the base URL, authentication and errors, see the REST API overview.

GET /v1/users/{user}/roles ​

  • Request: GET /v1/users/{user}/roles
  • Operation: ListRoles
  • Operation ID: Role_List
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes

Example request

bash
curl 'https://YOUR_SERVER/v1/users/YOUR_USER/roles' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

Response example (200)

json
[
  {
    "allow": {
      "Alarm": {
        "*": [
          "List*",
          "Read*",
          "UpdateAlarmInstance"
        ]
      },
      "Bucket": {
        "*": [
          "List*",
          "Read*"
        ]
      },
      "Dashboard": {
        "*": [
          "List*",
          "Read*"
        ]
      },
      "Device": {
        "*": [
          "List*",
          "Read*",
          "AccessDeviceResources"
        ]
      }
    },
    "created": 1792263090707,
    "enabled": true,
    "modified": 1792263090707,
    "role": "operator"
  },
  {
    "allow": {
      "Bucket": {
        "*": [
          "List*",
          "Read*"
        ]
      },
      "Dashboard": {
        "*": [
          "List*",
          "Read*"
        ]
      },
      "Device": {
        "*": [
          "List*",
          "Read*"
        ]
      }
    },
    "created": 1792263090707,
    "enabled": true,
    "modified": 1792263090707,
    "role": "viewer"
  }
]

POST /v1/users/{user}/roles ​

  • Request: POST /v1/users/{user}/roles
  • Operation: CreateRole
  • Operation ID: Role_Create
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes

Request body (application/json, required)

A global role is a named set of permissions of the account, reusable by members of any of its projects (members.global_roles). Permissions: {<resource type>: {<resource id or *>: action | [actions]}}; actions accept a trailing * (Read*, List*).

FieldTypeRequiredConstraintsDescription
allowobjectno
allow.*objectnoMinimum properties: 1
allow.*.*string or array of string or objectno
allow.*.*stringnoPattern: ^[a-zA-Z0-9_\*]{1,64}$|^\*$Variant 1:
allow.*.*array of string or objectnoVariant 2:
allow.*.*[]stringnoPattern: ^[a-zA-Z0-9_\*]{1,64}$|^\*$Variant 2: Variant 1:
allow.*.*[]objectnoVariant 2: Variant 2:
allow.*.*[].*string or array of stringnoVariant 1: Pattern: ^[a-zA-Z0-9_\*]{1,32}$|^\*$Variant 2: Variant 2:
denyobjectno
deny.*objectnoMinimum properties: 1
deny.*.*string or array of string or objectno
deny.*.*stringnoPattern: ^[a-zA-Z0-9_\*]{1,64}$|^\*$Variant 1:
deny.*.*array of string or objectnoVariant 2:
deny.*.*[]stringnoPattern: ^[a-zA-Z0-9_\*]{1,64}$|^\*$Variant 2: Variant 1:
deny.*.*[]objectnoVariant 2: Variant 2:
deny.*.*[].*string or array of stringnoVariant 1: Pattern: ^[a-zA-Z0-9_\*]{1,32}$|^\*$Variant 2: Variant 2:
enabledbooleanyes
rolestringyesPattern: ^[a-zA-Z0-9_-]{1,32}$A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.

Example request: Operator

bash
curl -X POST 'https://YOUR_SERVER/v1/users/YOUR_USER/roles' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "allow": {
    "Alarm": {
      "*": [
        "List*",
        "Read*",
        "UpdateAlarmInstance"
      ]
    },
    "Bucket": {
      "*": [
        "List*",
        "Read*"
      ]
    },
    "Dashboard": {
      "*": [
        "List*",
        "Read*"
      ]
    },
    "Device": {
      "*": [
        "List*",
        "Read*",
        "AccessDeviceResources"
      ]
    }
  },
  "enabled": true,
  "role": "operator"
}'

Example body: Viewer

json
{
  "allow": {
    "Bucket": {
      "*": [
        "List*",
        "Read*"
      ]
    },
    "Dashboard": {
      "*": [
        "List*",
        "Read*"
      ]
    },
    "Device": {
      "*": [
        "List*",
        "Read*"
      ]
    }
  },
  "enabled": true,
  "role": "viewer"
}

Responses

StatusDescription
200ok
401unauthorized
403forbidden

GET /v1/users/{user}/roles/{role} ​

  • Request: GET /v1/users/{user}/roles/
  • Operation: ReadRoleConfig
  • Operation ID: Role_ReadConfig
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
rolepathstringyes

Example request

bash
curl 'https://YOUR_SERVER/v1/users/YOUR_USER/roles/YOUR_ROLE' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

Response example (200, Operator)

json
{
  "allow": {
    "Alarm": {
      "*": [
        "List*",
        "Read*",
        "UpdateAlarmInstance"
      ]
    },
    "Bucket": {
      "*": [
        "List*",
        "Read*"
      ]
    },
    "Dashboard": {
      "*": [
        "List*",
        "Read*"
      ]
    },
    "Device": {
      "*": [
        "List*",
        "Read*",
        "AccessDeviceResources"
      ]
    }
  },
  "created": 1792263090707,
  "enabled": true,
  "modified": 1792263090707,
  "role": "operator"
}

Response example (200, Viewer)

json
{
  "allow": {
    "Bucket": {
      "*": [
        "List*",
        "Read*"
      ]
    },
    "Dashboard": {
      "*": [
        "List*",
        "Read*"
      ]
    },
    "Device": {
      "*": [
        "List*",
        "Read*"
      ]
    }
  },
  "created": 1792263090707,
  "enabled": true,
  "modified": 1792263090707,
  "role": "viewer"
}

PUT /v1/users/{user}/roles/{role} ​

  • Request: PUT /v1/users/{user}/roles/
  • Operation: UpdateRole
  • Operation ID: Role_Update
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
rolepathstringyes

Request body (application/json, required)

FieldTypeRequiredConstraintsDescription
allowobjectno
allow.*objectnoMinimum properties: 1
allow.*.*string or array of string or objectno
allow.*.*stringnoPattern: ^[a-zA-Z0-9_\*]{1,64}$|^\*$Variant 1:
allow.*.*array of string or objectnoVariant 2:
allow.*.*[]stringnoPattern: ^[a-zA-Z0-9_\*]{1,64}$|^\*$Variant 2: Variant 1:
allow.*.*[]objectnoVariant 2: Variant 2:
allow.*.*[].*string or array of stringnoVariant 1: Pattern: ^[a-zA-Z0-9_\*]{1,32}$|^\*$Variant 2: Variant 2:
denyobjectno
deny.*objectnoMinimum properties: 1
deny.*.*string or array of string or objectno
deny.*.*stringnoPattern: ^[a-zA-Z0-9_\*]{1,64}$|^\*$Variant 1:
deny.*.*array of string or objectnoVariant 2:
deny.*.*[]stringnoPattern: ^[a-zA-Z0-9_\*]{1,64}$|^\*$Variant 2: Variant 1:
deny.*.*[]objectnoVariant 2: Variant 2:
deny.*.*[].*string or array of stringnoVariant 1: Pattern: ^[a-zA-Z0-9_\*]{1,32}$|^\*$Variant 2: Variant 2:
enabledbooleanno

Example request: Disable the role

bash
curl -X PUT 'https://YOUR_SERVER/v1/users/YOUR_USER/roles/YOUR_ROLE' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "enabled": false
}'

Example body: Replace its permissions

json
{
  "allow": {
    "Dashboard": {
      "*": [
        "List*",
        "Read*"
      ]
    },
    "Device": {
      "*": [
        "List*",
        "Read*"
      ]
    }
  }
}

Responses

StatusDescription
200ok
401unauthorized
403forbidden

DELETE /v1/users/{user}/roles/{role} ​

  • Request: DELETE /v1/users/{user}/roles/
  • Operation: DeleteRole
  • Operation ID: Role_Delete
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
rolepathstringyes

Example request

bash
curl -X DELETE 'https://YOUR_SERVER/v1/users/YOUR_USER/roles/YOUR_ROLE' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

GET /v1/users/{user}/roles/{role}/clone ​

  • Request: GET /v1/users/{user}/roles/{role}/clone
  • Operation: CloneRoleConfig
  • Operation ID: Role_CloneConfig
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
rolepathstringyes

Example request

bash
curl 'https://YOUR_SERVER/v1/users/YOUR_USER/roles/YOUR_ROLE/clone' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

POST /v1/users/{user}/roles/{role}/clone ​

  • Request: POST /v1/users/{user}/roles/{role}/clone
  • Operation: CloneRole
  • Operation ID: Role_Clone
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
rolepathstringyes

Request body (application/json, required)

FieldTypeRequiredConstraintsDescription
descriptionstringnoMaximum length: 255A brief description of the resource, providing context or additional information, limited to 255 characters.
enabledbooleanno
namestringnoMaximum length: 255The name of the resource, limited to 255 characters. It can include any character.
rolestringyesPattern: ^[a-zA-Z0-9_-]{1,32}$A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.

Example request: Copy with a new id

bash
curl -X POST 'https://YOUR_SERVER/v1/users/YOUR_USER/roles/YOUR_ROLE/clone' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "role": "copy_of_role"
}'

Example body: Copy with name and description

json
{
  "description": "Same configuration as the original, for production line 2",
  "name": "Line 2 copy",
  "role": "line_2_role"
}

Responses

StatusDescription
200ok
401unauthorized
403forbidden