Role

>>>

GET /api/v3/roles
List all roles

Returns a list of all roles belonging to an account as per the specified criteria. This API is paginated and returns 20 roles by default. A role is uniquely identified by a 'role_key'. This key should be used in all the other API referencing a particular role.

Params

Param name Description
page
optional

Page number of results to be fetched, Default 1


Value: Must be Integer.
per
optional

Number of roles records to be returned in one page, Default 20


Value: Must be Integer.
order_by
optional

Field on which resultant roles should be sorted


Value: Must be a String
order
optional

Order, asc or desc, in which results should be sorted


Value: Must be a String
timestamp_format
optional

Format, “str” or “int”, in which timestamps should be returned, Default “int”


Value: Must be a String
search
optional

Keywords based on which roles should be searched. Currently you can search roles on - role_key, name


Value: Must be a String
scope
optional

Matching condition if multiple keywords are specified for search. Valid values are “all” or “any”. Default is “all”


Value: Must be a String
pretty
optional

Return a pretty formatted response if true, Default is false


Value: Must be a Boolean
field_list
optional

List of fields required in the result.


Value: Must be an array of any type
fields
optional

[Deprecated]Comma separated list of fields required in the result.


Value: Must be a String
is_oem
optional

Returns roles of child accounts along with roles of oem account if is_oem flag is true.


Value: Must be one of: <code>true</code>, <code>false</code>, <code>true</code>, <code>false</code>.

Examples

Request - listing all roles without any criteria
  curl -X GET  -H "Content-Type:application/json" -H "X-Auth-Token:WtUFnj8pvSxVnH9e_xkq7A" https://api.datonis.io/api/v3/roles

Response (returns first 20 records)
{
  "total_count": 5,
  "page": 1,
  "roles": [
    {
      "abilities": [
        0
      ],
      "account_admin": true,
      "role_key": "2e46ec4f56",
      "name": "Account Admin",
      "permissions": [
        {
          "class": "all",
          "operation": null,
          "seqno": 0
        }
      ],
      "created_at": 1448282945,
      "updated_at": 1448282945
    },
    {
      "abilities": [
        1,
        11,
        17,
        6
      ],
      "account_admin": false,
      "role_key": "9c6dcctaec",
      "name": "Read Only",
      "permissions": [
        {
          "class": "thing",
          "operation": "read",
          "seqno": 1
        },
        {
          "class": "sensor",
          "operation": "read",
          "seqno": 1
        },
        {
          "class": "rule",
          "operation": "read",
          "seqno": 6
        },
        {
          "class": "instruction",
          "operation": "read",
          "seqno": 11
        },
        {
          "class": "group",
          "operation": "read",
          "seqno": 17
        }
      ],
      "created_at": 1448282945,
      "updated_at": 1448282945
    },
    {
      "abilities": [
        3
      ],
      "account_admin": false,
      "role_key": "d5552947a8",
      "name": "Agent",
      "permissions": [
        {
          "class": "thing",
          "operation": "read",
          "seqno": 1
        },
        {
          "class": "thing",
          "operation": "update",
          "seqno": 3
        },
        {
          "class": "sensor",
          "operation": "read",
 ...
Request - listing roles by specifying number of roles to be returned at a time (page size) and specific set to be returned (page)
  curl -X GET  -H "Content-Type:application/json" -H "X-Auth-Token:WtUFnj8pvSxVnH9e_xkq7A" -d '{"per":"2", "page":"2"}' https://api.datonis.io/api/v3/roles

Response (returns page 2 with 2 roles per page)
{
  "total_count": 5,
  "page": "2",
  "roles": [
    {
      "abilities": [
        3
      ],
      "account_admin": false,
      "role_key": "d5552947a8",
      "name": "Agent",
      "permissions": [
        {
          "class": "thing",
          "operation": "read",
          "seqno": 1
        },
        {
          "class": "thing",
          "operation": "update",
          "seqno": 3
        },
        {
          "class": "sensor",
          "operation": "read",
          "seqno": 1
        },
        {
          "class": "sensor",
          "operation": "update",
          "seqno": 3
        }
      ],
      "created_at": 1448282945,
      "updated_at": 1448282945
    },
    {
      "abilities": [
        5
      ],
      "account_admin": false,
      "role_key": "6t9f5bed7f",
      "name": "Thing_only",
      "permissions": [
        {
          "class": "thing",
          "operation": "read",
          "seqno": 1
        },
        {
          "class": "thing",
          "operation": "create",
          "seqno": 2
        },
        {
          "class": "thing",
          "operation": "update",
          "seqno": 3
        },
        {
          "class": "thing",
          "operation": "delete",
          "seqno": 4
        },
        {
          "class": "thing",
          "operation": "all",
          "seqno": 5
        },
        {
          "class": "sensor",
          "operation": "read",
          "seqno": 1
        },
        {
          "class": "sensor",
          "operation": "create",
          "seqno": 2
        },
        {
          "class":...
>>>

GET /api/v3/roles/:role_key
Fetch information for a role

Returns details of the role requested

Params

Param name Description
pretty
optional

Return a pretty formatted response if true, Default is false


Value: Must be a Boolean
is_oem
optional

Show role of child account if is_oem flag is true.


Value: Must be one of: <code>true</code>, <code>false</code>, <code>true</code>, <code>false</code>.

Examples

Request - get details of the specified role (role specified as a part of the url)
  curl -X GET  -H "Content-Type:application/json" -H "X-Auth-Token:WtUFnj8pvSxVnH9e_xkq7A"  https://api.datonis.io/api/v3/roles/d5552947a8

Response (returns details of the role requested)
{
  "role": {
    "abilities": [
      3
    ],
    "account_admin": false,
    "role_key": "d5552947a8",
    "name": "Agent",
    "permissions": [
      {
        "class": "thing",
        "operation": "read",
        "seqno": 1
      },
      {
        "class": "thing",
        "operation": "update",
        "seqno": 3
      },
      {
        "class": "sensor",
        "operation": "read",
        "seqno": 1
      },
      {
        "class": "sensor",
        "operation": "update",
        "seqno": 3
      }
    ],
    "created_at": 1448282945,
    "updated_at": 1448282945
  }
}
>>>

POST /api/v3/roles
Create a role

Creates a role with given parameters

Params

Param name Description
pretty
optional

Return a pretty formatted response if true, Default is false


Value: Must be a Boolean
is_oem
optional

Create role in child account by oem user if is_oem flag is true.


Value: Must be a Boolean
child_organisation_key
optional

Organisation key of child account where oem user wants to create role. Required field if is_oem is present.


Value: Must be a String

Examples

Request
  curl -X POST -H "Content-Type:application/json" -H "X-Auth-Token:WtUFnj8pvSxVnH9e_xkq7A" -d '{"role":{"name":"Write Only", "abilities":[3]}}' https://api.datonis.io/api/v3/roles

Response (returns details of the role created)
{
  "role": {
    "abilities": [
      3
    ],
    "account_admin": false,
    "role_key": "517d8e4695",
    "name": "Write Only",
    "permissions": [
      {
        "class": "role",
        "operation": "read",
        "seqno": 1
      },
      {
        "class": "role",
        "operation": "update",
        "seqno": 3
      }
    ]
  }
}
>>>

DELETE /api/v3/roles/:role_key
Delete a role

Deletes the specified role from the system. All associated data is also lost.

Params

Param name Description
pretty
optional

Return a pretty formatted response if true, Default is false


Value: Must be a Boolean
is_oem
optional

Delete role in child account by oem user if is_oem flag is true.


Value: Must be a Boolean

Examples

Request
  curl -X DELETE -H "Content-Type:application/json" -H "X-Auth-Token:WtUFnj8pvSxVnH9e_xkq7A"  https://api.datonis.io/api/v3/roles/517d8e4695

Response
{
}
>>>

PUT /api/v3/roles/:role_key
Updates a role

Updates a role with given parameters

Params

Param name Description
pretty
optional

Return a pretty formatted response if true, Default is false


Value: Must be a Boolean
is_oem
optional

Update role in child account by oem user if is_oem flag is true.


Value: Must be a Boolean

Examples

Request - containing parameters to be modified
  curl -X PUT -H "Content-Type:application/json" -H "X-Auth-Token:WtUFnj8pvSxVnH9e_xkq7A" -d '{"role":{"abilities":[5],"name":"Write Only"}}}' https://api.datonis.io/api/v3/roles/517d8e4695

Response (returns details of the role updated)
{
  "role": {
    "abilities": [
      5
    ],
    "account_admin": false,
    "role_key": "517d8e4695",
    "name": "Write Only",
    "permissions": [
      {
        "class": "role",
        "operation": "read",
        "seqno": 1
      },
      {
        "class": "role",
        "operation": "create",
        "seqno": 2
      },
      {
        "class": "role",
        "operation": "update",
        "seqno": 3
      },
      {
        "class": "role",
        "operation": "delete",
        "seqno": 4
      },
      {
        "class": "role",
        "operation": "all",
        "seqno": 5
      }
    ]
  }
}