Skip to content

Groups

Group Data Structure

A group is a component that allows grouping of users and API keys, allowing fine-grained permissions on type-specific level by using a list of rules.

In responses, a group looks like this:

{
  "rules": [
    {
      "update": false,
      "type": "device",
      "regex": ".*",
      "read": true,
      "id": "7d785fd2-4530-4d2c-842e-157ae734bc6c",
      "delete": false,
      "create": false
    },
    {
      "update": false,
      "type": "tag",
      "regex": ".*",
      "read": true,
      "id": "db9a176e-3c44-4935-b131-05dd953843ec",
      "delete": false,
      "create": false
    },
    {
      "update": false,
      "type": "parser",
      "regex": ".*",
      "read": true,
      "id": "9b03c350-fc72-4c9a-b0e0-6aa2dba80a31",
      "delete": false,
      "create": false
    },
    {
      "update": false,
      "type": "driver",
      "regex": ".*",
      "read": true,
      "id": "fa850535-2643-4d88-a4f3-8714260654ea",
      "delete": false,
      "create": false
    },
    {
      "update": false,
      "type": "user",
      "regex": ".*",
      "read": true,
      "id": "3ed7cb04-9198-4e73-815c-b9bd1b84bd3d",
      "delete": false,
      "create": false
    }
  ],
  "name": "Read-Only Access",
  "mandate_id": "50e032fb-964f-440d-9b9a-47870667373c",
  "id": "5eb9f96a-1985-4eda-9735-27541dc92098",
}
Key Example Description
id 3e097a97-e504-4b4b-8182-ae148f2109f3 Unique group ID (UUID4)
rules [] An array of rules providing a type, a regular expression to match against and boolean values for CRUD operations
inserted_at 2017-07-31T12:15:18.289981Z Date of the creation to the group
updated_at 2017-07-31T12:15:18.289981Z Date of the last edit of the group
mandate_id cee40cb2-f58c-4ca8-ae91-4ae76cba5119 Reference to a mandate to which this group belongs
name Read-Only Access Name of the group

A rule will consist of the following fields:

{
  "update": false,
  "type": "user",
  "regex": ".*",
  "read": true,
  "id": "3ed7cb04-9198-4e73-815c-b9bd1b84bd3d",
  "delete": false,
  "create": false
}
Key Example Description
id 3e097a97-e504-4b4b-8182-ae148f2109f3 Unique rule ID (UUID4)
type device Type of the resource, may be device, tag, parser, driver, apikey
update true May the API key or user change this resource
delete true May the API key or user remove this resource
create true May the API key or user create a new instance of this resource
read true May the API key or user access this resource
regex ^PowerMeter.* A regular expression that will match resource-specific fields

Supported fields to match the regular expression against are:

Type Fields
device id, name, slug
tag id, name, slug
user id, name, email
parser id, name
driver id, name
apikey id, name

List all Groups

Method: GET, Endpoint: /groups

Example Request

GET https://element-iot.com/api/v1/groups?auth=46cb688e2c0b468e26e914235d4b73ea

Example Response

{
  "status": 200,
  "retrieve_after_id": "a70a234e-d186-4ca8-836b-74816738939e",
  "ok": true,
  "body": [
    // Contains an array of groups
  ]
}

This endpoint returns a paginated list of groups.

If you want to configure the sort order or restrict the results to a specific time interval, please refer to the Pagination section of this documentation.

Show a single Group

Method: GET, Endpoint: /groups/:group_id

Example Request

GET https://element-iot.com/api/v1/groups/adedada4-c93d-425c-a98d-ba79d930fa9c?auth=46cb688e2c0b468e26e914235d4b73ea

Example Response

{
  "status": 200,
  "ok": true,
  "body": {
    // Contains the group
  }
}

The group ID must be the id of the group.