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.