Skip to main content

API

Reference​

API reference in the Swagger UI can be found at: https://api.magistrala.abstractmachines.fr

Users​

Create User​

To start working with the SuperMQ system, you need to create a user account.

Identity, which can be email-address (this must be unique as it identifies the user) and secret (password must contain at least 8 characters).

curl -sSiX POST http://localhost/users -H "Content-Type: application/json" [-H "Authorization: Bearer <user_token>"] -d @- << EOF
{
  "name": "[name]",
  "tags": ["[tag1]", "[tag2]"],
  "credentials": {
    "identity": "<user_identity>",
    "secret": "<user_secret>"
  },
  "metadata": {
    "[key1]": "[value1]",
    "[key2]": "[value2]"
  },
  "status": "[status]",
  "role": "[role]"
}
EOF

For example:

curl -sSiX POST http://localhost/users -H "Content-Type: application/json" -d @- << EOF
{
  "name": "John Doe",
  "credentials": {
    "identity": "john.doe@email.com",
    "secret": "12345678"
  }
}
EOF

HTTP/1.1 201 Created
Server: nginx/1.23.3
Date: Wed, 14 Jun 2023 13:45:38 GMT
Content-Type: application/json
Content-Length: 223
Connection: keep-alive
Location: /users/4f22fa45-50ca-491b-a7c9-680a2608dc13
Access-Control-Expose-Headers: Location

{
  "id": "4f22fa45-50ca-491b-a7c9-680a2608dc13",
  "name": "John Doe",
  "credentials": { "identity": "john.doe@email.com" },
  "created_at": "2023-06-14T13:45:38.808423Z",
  "updated_at": "0001-01-01T00:00:00Z",
  "status": "enabled"
}

You can also use <user_token> so that the owner of the new user is the one identified by the <user_token> for example:

curl -sSiX POST http://localhost/users -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
{
  "name": "John Doe",
  "credentials": {
    "identity": "jane.doe@email.com",
    "secret": "12345678"
  },
}
EOF

HTTP/1.1 201 Created
Server: nginx/1.23.3
Date: Wed, 14 Jun 2023 13:46:47 GMT
Content-Type: application/json
Content-Length: 252
Connection: keep-alive
Location: /users/1890c034-7ef9-4cde-83df-d78ea1d4d281
Access-Control-Expose-Headers: Location

{
  "id": "1890c034-7ef9-4cde-83df-d78ea1d4d281",
  "owner": "94939159-d129-4f17-9e4e-cc2d615539d7",
  "credentials": { "identity": "jane.doe@email.com" },
  "created_at": "2023-06-14T13:46:47.322648Z",
  "updated_at": "0001-01-01T00:00:00Z",
  "status": "enabled"
}

Create Token​

To log in to the SuperMQ system, you need to create a user_token.

curl -sSiX POST http://localhost/users/tokens/issue -H "Content-Type: application/json" -d @- << EOF
{
  "identity": "<user_identity>",
  "secret": "<user_secret>"
}
EOF

For example:

curl -sSiX POST http://localhost/users/tokens/issue -H "Content-Type: application/json" -d @- << EOF
{
  "identity": "john.doe@email.com",
  "secret": "12345678"
}
EOF

HTTP/1.1 201 Created
Server: nginx/1.23.3
Date: Wed, 14 Jun 2023 13:47:32 GMT
Content-Type: application/json
Content-Length: 709
Connection: keep-alive
Access-Control-Expose-Headers: Location

{
  "access_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2ODY3NTEzNTIsImlhdCI6MTY4Njc1MDQ1MiwiaWRlbnRpdHkiOiJqb2huLmRvZUBlbWFpbC5jb20iLCJpc3MiOiJjbGllbnRzLmF1dGgiLCJzdWIiOiI5NDkzOTE1OS1kMTI5LTRmMTctOWU0ZS1jYzJkNjE1NTM5ZDciLCJ0eXBlIjoiYWNjZXNzIn0.AND1sm6mN2wgUxVkDhpipCoNa87KPMghGaS5-4dU0iZaqGIUhWScrEJwOahT9ts1TZSd1qEcANTIffJ_y2Pbsg",
  "refresh_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2ODY4MzY4NTIsImlhdCI6MTY4Njc1MDQ1MiwiaWRlbnRpdHkiOiJqb2huLmRvZUBlbWFpbC5jb20iLCJpc3MiOiJjbGllbnRzLmF1dGgiLCJzdWIiOiI5NDkzOTE1OS1kMTI5LTRmMTctOWU0ZS1jYzJkNjE1NTM5ZDciLCJ0eXBlIjoicmVmcmVzaCJ9.z3OWCHhNHNuvkzBqEAoLKWS6vpFLkIYXhH9cZogSCXd109-BbKVlLvYKmja-hkhaj_XDJKySDN3voiazBr_WTA",
  "access_type": "Bearer"
}

Refresh Token​

To issue another access_token after getting expired, you need to use a refresh_token.

curl -sSiX POST http://localhost/users/tokens/refresh -H "Content-Type: application/json" -H "Authorization: Bearer <refresh_token>"

For example:

curl -sSiX POST http://localhost/users/tokens/refresh -H "Content-Type: application/json" -H "Authorization: Bearer <refresh_token>"

HTTP/1.1 201 Created
Server: nginx/1.23.3
Date: Wed, 14 Jun 2023 13:49:45 GMT
Content-Type: application/json
Content-Length: 709
Connection: keep-alive
Access-Control-Expose-Headers: Location

{
  "access_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2ODY3NTE0ODUsImlhdCI6MTY4Njc1MDU4NSwiaWRlbnRpdHkiOiJqb2huLmRvZUBlbWFpbC5jb20iLCJpc3MiOiJjbGllbnRzLmF1dGgiLCJzdWIiOiI5NDkzOTE1OS1kMTI5LTRmMTctOWU0ZS1jYzJkNjE1NTM5ZDciLCJ0eXBlIjoiYWNjZXNzIn0.zZcUH12x7Tlnecrc3AAFnu3xbW4wAOGifWZMnba2EnhosHWDuSN4N7s2S7OxPOrBGAG_daKvkA65mi5n1sxi9A",
  "refresh_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2ODY4MzY5ODUsImlhdCI6MTY4Njc1MDU4NSwiaWRlbnRpdHkiOiJqb2huLmRvZUBlbWFpbC5jb20iLCJpc3MiOiJjbGllbnRzLmF1dGgiLCJzdWIiOiI5NDkzOTE1OS1kMTI5LTRmMTctOWU0ZS1jYzJkNjE1NTM5ZDciLCJ0eXBlIjoicmVmcmVzaCJ9.AjxJ5xlUUSjW99ECUAU19ONeCs8WlRl52Ost2qGTADxHGYBjPMqctruyoTYJbdORtL5f2RTxZsnLX_1vLKRY2A",
  "access_type": "Bearer"
}

Get User Profile​

You can always check the user profile that is logged-in by using the user_token.

curl -sSiX GET http://localhost/users/profile -H "Authorization: Bearer <user_token>"

For example:

curl -sSiX GET http://localhost/users/profile -H "Authorization: Bearer <user_token>"

HTTP/1.1 200 OK
Server: nginx/1.23.3
Date: Wed, 14 Jun 2023 13:51:59 GMT
Content-Type: application/json
Content-Length: 312
Connection: keep-alive
Access-Control-Expose-Headers: Location

{
  "id": "1890c034-7ef9-4cde-83df-d78ea1d4d281",
  "owner": "94939159-d129-4f17-9e4e-cc2d615539d7",
  "credentials": {
    "identity": "jane.doe@email.com"
  },
  "created_at": "2023-06-14T13:46:47.322648Z",
  "updated_at": "0001-01-01T00:00:00Z",
  "status": "enabled"
}

Get User​

You can always check the user entity by entering the user ID and user_token.

curl -sSiX GET http://localhost/users/<user_id> -H "Authorization: Bearer <user_token>"

For example:

curl -sSiX GET http://localhost/users/1890c034-7ef9-4cde-83df-d78ea1d4d281  -H "Authorization: Bearer <user_token>"

HTTP/1.1 200 OK
Server: nginx/1.23.3
Date: Wed, 14 Jun 2023 13:51:59 GMT
Content-Type: application/json
Content-Length: 312
Connection: keep-alive
Access-Control-Expose-Headers: Location

{
  "id": "1890c034-7ef9-4cde-83df-d78ea1d4d281",
  "owner": "94939159-d129-4f17-9e4e-cc2d615539d7",
  "credentials": {
    "identity": "jane.doe@email.com"
  },
  "created_at": "2023-06-14T13:46:47.322648Z",
  "updated_at": "0001-01-01T00:00:00Z",
  "status": "enabled"
}

Get Users​

You can get all users in the database by querying /users endpoint.

curl -sSiX GET http://localhost/users -H "Authorization: Bearer <user_token>"

For example:

curl -sSiX GET http://localhost/users -H "Authorization: Bearer <user_token>"

HTTP/1.1 200 OK
Server: nginx/1.23.3
Date: Wed, 14 Jun 2023 13:52:36 GMT
Content-Type: application/json
Content-Length: 285
Connection: keep-alive
Access-Control-Expose-Headers: Location

{
  "limit": 10,
  "total": 1,
  "users": [
    {
      "id": "1890c034-7ef9-4cde-83df-d78ea1d4d281",
      "owner": "94939159-d129-4f17-9e4e-cc2d615539d7",
      "credentials": { "identity": "jane.doe@email.com" },
      "created_at": "2023-06-14T13:46:47.322648Z",
      "updated_at": "0001-01-01T00:00:00Z",
      "status": "enabled"
    }
  ]
}

If you want to paginate your results then use offset, limit, metadata, name, identity, tag, status and visbility as query parameters.

curl -sSiX GET http://localhost/users?[offset=<offset>]&[limit=<limit>]&[identity=<identity>]&[name=<name>]&[tag=<tag>]&[status=<status>]&[visibility=<visibility>] -H "Authorization: Bearer <user_token>"

For example:

curl -sSiX GET http://localhost/users?offset=0&limit=5&identity=jane.doe@email.com -H "Authorization: Bearer <user_token>"

HTTP/1.1 200 OK
Server: nginx/1.23.3
Date: Wed, 14 Jun 2023 13:53:16 GMT
Content-Type: application/json
Content-Length: 284
Connection: keep-alive
Access-Control-Expose-Headers: Location

{
  "limit": 5,
  "total": 1,
  "users": [
    {
      "id": "1890c034-7ef9-4cde-83df-d78ea1d4d281",
      "owner": "94939159-d129-4f17-9e4e-cc2d615539d7",
      "credentials": { "identity": "jane.doe@email.com" },
      "created_at": "2023-06-14T13:46:47.322648Z",
      "updated_at": "0001-01-01T00:00:00Z",
      "status": "enabled"
    }
  ]
}

Update User​

Updating user's name and/or metadata

curl -sSiX PATCH http://localhost/users/<user_id> -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
{
  "name": "[new_name]",
  "metadata": {
    "[key1]": "[value1]",
    "[key2]": "[value2]"
  }
}
EOF

For example:

curl -sSiX PATCH http://localhost/users/1890c034-7ef9-4cde-83df-d78ea1d4d281 -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
{
  "name": "Jane Doe",
  "metadata": {
    "location": "london"
  }
}
EOF

HTTP/1.1 200 OK
Server: nginx/1.23.3
Date: Wed, 14 Jun 2023 13:54:40 GMT
Content-Type: application/json
Content-Length: 354
Connection: keep-alive
Access-Control-Expose-Headers: Location

{
  "id": "1890c034-7ef9-4cde-83df-d78ea1d4d281",
  "name": "Jane Doe",
  "owner": "94939159-d129-4f17-9e4e-cc2d615539d7",
  "credentials": { "identity": "jane.doe@email.com" },
  "metadata": { "location": "london" },
  "created_at": "2023-06-14T13:46:47.322648Z",
  "updated_at": "2023-06-14T13:54:40.208005Z",
  "updated_by": "94939159-d129-4f17-9e4e-cc2d615539d7",
  "status": "enabled"
}

Update User Tags​

Updating user's tags

curl -sSiX PATCH http://localhost/users/<user_id>/tags -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
{
  "tags": [
    "[tag_1]",
    ...
    "[tag_N]"
  ]
}
EOF

For example:

curl -sSiX PATCH http://localhost/users/1890c034-7ef9-4cde-83df-d78ea1d4d281/tags -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
{
  "tags": ["male", "developer"]
}
EOF

HTTP/1.1 200 OK
Server: nginx/1.23.3
Date: Wed, 14 Jun 2023 13:55:18 GMT
Content-Type: application/json
Content-Length: 375
Connection: keep-alive
Access-Control-Expose-Headers: Location

{
  "id": "1890c034-7ef9-4cde-83df-d78ea1d4d281",
  "name": "Jane Doe",
  "tags": ["male", "developer"],
  "owner": "94939159-d129-4f17-9e4e-cc2d615539d7",
  "credentials": { "identity": "jane.doe@email.com" },
  "metadata": { "location": "london" },
  "created_at": "2023-06-14T13:46:47.322648Z",
  "updated_at": "2023-06-14T13:55:18.353027Z",
  "updated_by": "94939159-d129-4f17-9e4e-cc2d615539d7",
  "status": "enabled"
}

Update User Owner​

Updating user's owner

curl -sSiX PATCH http://localhost/users/<user_id>/owner -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
{
  "owner": "<owner_id>"
}
EOF

For example:

curl -sSiX PATCH http://localhost/users/1890c034-7ef9-4cde-83df-d78ea1d4d281/owner -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
{
  "owner": "532311a4-c13b-4061-b991-98dcae7a934e"
}
EOF

HTTP/1.1 200 OK
Server: nginx/1.23.3
Date: Wed, 14 Jun 2023 13:56:32 GMT
Content-Type: application/json
Content-Length: 375
Connection: keep-alive
Access-Control-Expose-Headers: Location

{
  "id": "1890c034-7ef9-4cde-83df-d78ea1d4d281",
  "name": "Jane Doe",
  "tags": ["male", "developer"],
  "owner": "532311a4-c13b-4061-b991-98dcae7a934e",
  "credentials": { "identity": "jane.doe@email.com" },
  "metadata": { "location": "london" },
  "created_at": "2023-06-14T13:46:47.322648Z",
  "updated_at": "2023-06-14T13:56:32.059484Z",
  "updated_by": "94939159-d129-4f17-9e4e-cc2d615539d7",
  "status": "enabled"
}

Update User Identity​

Updating user's identity

curl -sSiX PATCH http://localhost/users/<user_id>/identity -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
{
  "identity": "<user_identity>"
}
EOF

For example:

curl -sSiX PATCH http://localhost/users/1890c034-7ef9-4cde-83df-d78ea1d4d281/identity -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
{
  "identity": "updated.jane.doe@gmail.com"
}
EOF

HTTP/1.1 200 OK
Server: nginx/1.23.3
Date: Wed, 14 Jun 2023 13:59:53 GMT
Content-Type: application/json
Content-Length: 382
Connection: keep-alive
Access-Control-Expose-Headers: Location

{
  "id": "1890c034-7ef9-4cde-83df-d78ea1d4d281",
  "name": "Jane Doe",
  "tags": ["male", "developer"],
  "owner": "94939159-d129-4f17-9e4e-cc2d615539d7",
  "credentials": { "identity": "updated.jane.doe@gmail.com" },
  "metadata": { "location": "london" },
  "created_at": "2023-06-14T13:46:47.322648Z",
  "updated_at": "2023-06-14T13:59:53.422595Z",
  "updated_by": "94939159-d129-4f17-9e4e-cc2d615539d7",
  "status": "enabled"
}

Change Secret​

Changing the user secret can be done by calling the update secret method

curl -sSiX PATCH http://localhost/users/secret -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
{
  "old_secret": "<old_secret>",
  "new_secret": "<new_secret>"
}
EOF

For example:

curl -sSiX PATCH http://localhost/users/secret -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
{
  "old_secret": "12345678",
  "new_secret": "12345678a"
}
EOF

HTTP/1.1 200 OK
Server: nginx/1.23.3
Date: Wed, 14 Jun 2023 14:00:35 GMT
Content-Type: application/json
Content-Length: 281
Connection: keep-alive
Access-Control-Expose-Headers: Location

Enable User​

Changing the user status to enabled can be done by calling the enable user method

curl -sSiX POST http://localhost/users/<user_id>/enable -H "Authorization: Bearer <user_token>"

For example:

curl -sSiX POST http://localhost/users/1890c034-7ef9-4cde-83df-d78ea1d4d281/enable -H "Authorization: Bearer <user_token>"

HTTP/1.1 200 OK
Server: nginx/1.23.3
Date: Wed, 14 Jun 2023 14:01:25 GMT
Content-Type: application/json
Content-Length: 382
Connection: keep-alive
Access-Control-Expose-Headers: Location

{
  "id": "1890c034-7ef9-4cde-83df-d78ea1d4d281",
  "name": "Jane Doe",
  "tags": ["male", "developer"],
  "owner": "94939159-d129-4f17-9e4e-cc2d615539d7",
  "credentials": { "identity": "updated.jane.doe@gmail.com" },
  "metadata": { "location": "london" },
  "created_at": "2023-06-14T13:46:47.322648Z",
  "updated_at": "2023-06-14T13:59:53.422595Z",
  "updated_by": "94939159-d129-4f17-9e4e-cc2d615539d7",
  "status": "enabled"
}

Disable User​

Changing the user status to disabled can be done by calling the disable user method

curl -sSiX POST http://localhost/users/<user_id>/disable -H "Authorization: Bearer <user_token>"

For example:

curl -sSiX POST http://localhost/users/1890c034-7ef9-4cde-83df-d78ea1d4d281/disable -H "Authorization: Bearer <user_token>"

HTTP/1.1 200 OK
Server: nginx/1.23.3
Date: Wed, 14 Jun 2023 14:01:23 GMT
Content-Type: application/json
Content-Length: 383
Connection: keep-alive
Access-Control-Expose-Headers: Location

{
  "id": "1890c034-7ef9-4cde-83df-d78ea1d4d281",
  "name": "Jane Doe",
  "tags": ["male", "developer"],
  "owner": "94939159-d129-4f17-9e4e-cc2d615539d7",
  "credentials": { "identity": "updated.jane.doe@gmail.com" },
  "metadata": { "location": "london" },
  "created_at": "2023-06-14T13:46:47.322648Z",
  "updated_at": "2023-06-14T13:59:53.422595Z",
  "updated_by": "94939159-d129-4f17-9e4e-cc2d615539d7",
  "status": "disabled"
}

Get User Memberships​

You can get all groups a user is assigned to by calling the get user memberships method.

If you want to paginate your results then use offset, limit, metadata, name, status, parentID, ownerID, tree and dir as query parameters.

The user identified by the user_token must be assigned to the same group as the user with id user_id with c_list action. Alternatively, the user identified by the user_token must be the owner of the user with id user_id.

curl -sSiX GET http://localhost/users/<user_id>/memberships -H "Authorization: Bearer <user_token>"

For example:

curl -sSiX GET http://localhost/users/1890c034-7ef9-4cde-83df-d78ea1d4d281/memberships -H "Authorization: Bearer <user_token>"

HTTP/1.1 200 OK
Server: nginx/1.23.3
Date: Thu, 15 Jun 2023 11:22:18 GMT
Content-Type: application/json
Content-Length: 367
Connection: keep-alive
Access-Control-Expose-Headers: Location

{
  "limit": 0,
  "offset": 0,
  "memberships": [
    {
      "id": "2766ae94-9a08-4418-82ce-3b91cf2ccd3e",
      "owner_id": "94939159-d129-4f17-9e4e-cc2d615539d7",
      "name": "Data analysts",
      "description": "This group would be responsible for analyzing data collected from sensors.",
      "metadata": { "location": "london" },
      "created_at": "2023-06-15T09:41:42.860481Z",
      "updated_at": "2023-06-15T10:17:56.475241Z",
      "updated_by": "94939159-d129-4f17-9e4e-cc2d615539d7",
      "status": "enabled"
    }
  ]
}

Things​

Create Thing​

To create a thing, you need the thing and a user_token

curl -sSiX POST http://localhost/things -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
{
  "id": "[thing_id]",
  "name":"[thing_name]",
  "tags": ["[tag1]", "[tag2]"],
  "credentials": {
      "identity": "[thing-identity]",
      "secret":"[thing-secret]"
  },
    "metadata": {
      "[key1]": "[value1]",
      "[key2]": "[value2]"
  },
  "status": "[enabled|disabled]"
}
EOF

For example:

curl -sSiX POST http://localhost/things -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
{
  "name":"Temperature Sensor"
}
EOF

HTTP/1.1 201 Created
Server: nginx/1.23.3
Date: Thu, 15 Jun 2023 09:04:04 GMT
Content-Type: application/json
Content-Length: 280
Connection: keep-alive
Location: /things/48101ecd-1535-40c6-9ed8-5b1d21e371bb
Access-Control-Expose-Headers: Location

{
  "id": "48101ecd-1535-40c6-9ed8-5b1d21e371bb",
  "name": "Temperature Sensor",
  "owner": "94939159-d129-4f17-9e4e-cc2d615539d7",
  "credentials": { "secret": "c3f8c096-c60f-4375-8494-bca20a12fca7" },
  "created_at": "2023-06-15T09:04:04.292602664Z",
  "updated_at": "0001-01-01T00:00:00Z",
  "status": "enabled"
}

Create Thing with External ID​

It is often the case that the user will want to integrate the existing solutions, e.g. an asset management system, with the SuperMQ platform. To simplify the integration between the systems and avoid artificial cross-platform reference, such as special fields in SuperMQ Things metadata, it is possible to set SuperMQ Thing ID with an existing unique ID while create the Thing. This way, the user can set the existing ID as the Thing ID of a newly created Thing to keep reference between Thing and the asset that Thing represents.

The limitation is that the existing ID has to be unique in the SuperMQ domain.

To create a thing with an external ID, you need to provide the ID together with thing name, and other fields as well as a user_token

For example:

curl -sSiX POST http://localhost/things -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
{
  "id": "2766ae94-9a08-4418-82ce-3b91cf2ccd3e",
  "name":"Temperature Sensor"
}
EOF

HTTP/1.1 201 Created
Server: nginx/1.23.3
Date: Thu, 15 Jun 2023 09:05:06 GMT
Content-Type: application/json
Content-Length: 280
Connection: keep-alive
Location: /things/2766ae94-9a08-4418-82ce-3b91cf2ccd3e
Access-Control-Expose-Headers: Location

{
  "id": "2766ae94-9a08-4418-82ce-3b91cf2ccd3e",
  "name": "Temperature Sensor",
  "owner": "94939159-d129-4f17-9e4e-cc2d615539d7",
  "credentials": { "secret": "65ca03bd-eb6b-420b-9d5d-46d459d4f71c" },
  "created_at": "2023-06-15T09:05:06.538170496Z",
  "updated_at": "0001-01-01T00:00:00Z",
  "status": "enabled"
}

Create Thing with External Secret​

It is often the case that the user will want to integrate the existing solutions, e.g. an asset management system, with the SuperMQ platform. To simplify the integration between the systems and avoid artificial cross-platform reference, such as special fields in SuperMQ Things metadata, it is possible to set SuperMQ Thing secret with an existing unique secret when creating the Thing. This way, the user can set the existing secret as the Thing secret of a newly created Thing to keep reference between Thing and the asset that Thing represents. The limitation is that the existing secret has to be unique in the SuperMQ domain.

To create a thing with an external secret, you need to provide the secret together with thing name, and other fields as well as a user_token

For example:

curl -sSiX POST http://localhost/things -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
{
  "name":"Temperature Sensor"
  "credentials": {
    "secret": "94939159-9a08-4f17-9e4e-3b91cf2ccd3e"
  }
}
EOF

HTTP/1.1 201 Created
Server: nginx/1.23.3
Date: Thu, 15 Jun 2023 09:05:06 GMT
Content-Type: application/json
Content-Length: 280
Connection: keep-alive
Location: /things/2766ae94-9a08-4418-82ce-3b91cf2ccd3e
Access-Control-Expose-Headers: Location

{
  "id": "2766ae94-9a08-4418-82ce-3b91cf2ccd3e",
  "name": "Temperature Sensor",
  "owner": "94939159-d129-4f17-9e4e-cc2d615539d7",
  "credentials": { "secret": "94939159-9a08-4f17-9e4e-3b91cf2ccd3e" },
  "created_at": "2023-06-15T09:05:06.538170496Z",
  "updated_at": "0001-01-01T00:00:00Z",
  "status": "enabled"
}

Create Things​

You can create multiple things at once by entering a series of things structures and a user_token

curl -sSiX POST http://localhost/things/bulk -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
[
  {
    "id": "[thing_id]",
    "name":"[thing_name]",
    "tags": ["[tag1]", "[tag2]"],
    "credentials": {
        "identity": "[thing-identity]",
        "secret":"[thing-secret]"
    },
      "metadata": {
        "[key1]": "[value1]",
        "[key2]": "[value2]"
    },
    "status": "[enabled|disabled]"
  },
  {
    "id": "[thing_id]",
    "name":"[thing_name]",
    "tags": ["[tag1]", "[tag2]"],
    "credentials": {
        "identity": "[thing-identity]",
        "secret":"[thing-secret]"
    },
      "metadata": {
        "[key1]": "[value1]",
        "[key2]": "[value2]"
    },
    "status": "[enabled|disabled]"
  }
]
EOF

For example:

curl -sSiX POST http://localhost/things/bulk -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
[
  {
    "name":"Motion Sensor"
  },
  {
    "name":"Light Sensor"
  }
]
EOF

HTTP/1.1 200 OK
Server: nginx/1.23.3
Date: Thu, 15 Jun 2023 09:05:45 GMT
Content-Type: application/json
Content-Length: 583
Connection: keep-alive
Access-Control-Expose-Headers: Location

{
  "total": 2,
  "things": [
    {
      "id": "19f59b2d-1e9c-43db-bc84-5432bd52a83f",
      "name": "Motion Sensor",
      "owner": "94939159-d129-4f17-9e4e-cc2d615539d7",
      "credentials": { "secret": "941c380a-3a41-40e9-8b79-3087daa4f3a6" },
      "created_at": "2023-06-15T09:05:45.719182307Z",
      "updated_at": "0001-01-01T00:00:00Z",
      "status": "enabled"
    },
    {
      "id": "3709f2b0-9c73-413f-992e-7f6f9b396b0d",
      "name": "Light Sensor",
      "owner": "94939159-d129-4f17-9e4e-cc2d615539d7",
      "credentials": { "secret": "798ee6be-311b-4640-99e4-0ccb19e0dcb9" },
      "created_at": "2023-06-15T09:05:45.719186184Z",
      "updated_at": "0001-01-01T00:00:00Z",
      "status": "enabled"
    }
  ]
}

Create Things with external ID​

The same as creating a Thing with external ID the user can create multiple things at once by providing UUID v4 format unique ID in a series of things together with a user_token

For example:

curl -sSiX POST http://localhost/things/bulk -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
[
  {
    "id": "eb2670ba-a2be-4ea4-83cb-111111111111",
    "name":"Motion Sensor"
  },
  {
    "id": "eb2670ba-a2be-4ea4-83cb-111111111112",
    "name":"Light Sensor"
  }
]
EOF

HTTP/1.1 200 OK
Server: nginx/1.23.3
Date: Thu, 15 Jun 2023 09:06:17 GMT
Content-Type: application/json
Content-Length: 583
Connection: keep-alive
Access-Control-Expose-Headers: Location

{
  "total": 2,
  "things": [
    {
      "id": "eb2670ba-a2be-4ea4-83cb-111111111111",
      "name": "Motion Sensor",
      "owner": "94939159-d129-4f17-9e4e-cc2d615539d7",
      "credentials": { "secret": "325cda17-3a52-465d-89a7-2b63c7d0e3a6" },
      "created_at": "2023-06-15T09:06:17.967825372Z",
      "updated_at": "0001-01-01T00:00:00Z",
      "status": "enabled"
    },
    {
      "id": "eb2670ba-a2be-4ea4-83cb-111111111112",
      "name": "Light Sensor",
      "owner": "94939159-d129-4f17-9e4e-cc2d615539d7",
      "credentials": { "secret": "67b6cbb8-4a9e-4d32-8b9c-d7cd3352aa2b" },
      "created_at": "2023-06-15T09:06:17.967828689Z",
      "updated_at": "0001-01-01T00:00:00Z",
      "status": "enabled"
    }
  ]
}

Get Thing​

You can get thing entity by entering the thing ID and user_token

curl -sSiX GET http://localhost/things/<thing_id> -H "Authorization: Bearer <user_token>"

For example:

curl -sSiX GET http://localhost/things/48101ecd-1535-40c6-9ed8-5b1d21e371bb -H "Authorization: Bearer <user_token>"

HTTP/1.1 200 OK
Server: nginx/1.23.3
Date: Thu, 15 Jun 2023 09:07:30 GMT
Content-Type: application/json
Content-Length: 277
Connection: keep-alive
Access-Control-Expose-Headers: Location

{
  "id": "48101ecd-1535-40c6-9ed8-5b1d21e371bb",
  "name": "Temperature Sensor",
  "owner": "94939159-d129-4f17-9e4e-cc2d615539d7",
  "credentials": { "secret": "c3f8c096-c60f-4375-8494-bca20a12fca7" },
  "created_at": "2023-06-15T09:04:04.292602Z",
  "updated_at": "0001-01-01T00:00:00Z",
  "status": "enabled"
}

Get Things​

You can get all things in the database by querying /things endpoint.

curl -sSiX GET http://localhost/things -H "Authorization: Bearer <user_token>"

For example:

curl -sSiX GET http://localhost/things -H "Authorization: Bearer <user_token>"

HTTP/1.1 200 OK
Server: nginx/1.23.3
Date: Thu, 15 Jun 2023 09:07:59 GMT
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Access-Control-Expose-Headers: Location

{
  "limit": 10,
  "total": 8,
  "things": [
    {
      "id": "f3047c10-f2c7-4d53-b3c0-bc56c560c546",
      "name": "Humidity Sensor",
      "owner": "94939159-d129-4f17-9e4e-cc2d615539d7",
      "credentials": { "secret": "6d11a91f-0bd8-41aa-8e1b-4c6338329c9c" },
      "created_at": "2023-06-14T12:04:12.740098Z",
      "updated_at": "0001-01-01T00:00:00Z",
      "status": "enabled"
    },
    {
      "id": "04b0b2d1-fdaf-4b66-96a0-740a3151db4c",
      "name": "UV Sensor",
      "owner": "94939159-d129-4f17-9e4e-cc2d615539d7",
      "credentials": { "secret": "a1e5d77f-8903-4cef-87b1-d793a3c28de3" },
      "created_at": "2023-06-14T12:04:56.245743Z",
      "updated_at": "0001-01-01T00:00:00Z",
      "status": "enabled"
    },
    {
      "id": "48101ecd-1535-40c6-9ed8-5b1d21e371bb",
      "name": "Temperature Sensor",
      "owner": "94939159-d129-4f17-9e4e-cc2d615539d7",
      "credentials": { "secret": "c3f8c096-c60f-4375-8494-bca20a12fca7" },
      "created_at": "2023-06-15T09:04:04.292602Z",
      "updated_at": "0001-01-01T00:00:00Z",
      "status": "enabled"
    },
    {
      "id": "2766ae94-9a08-4418-82ce-3b91cf2ccd3e",
      "name": "Temperature Sensor",
      "owner": "94939159-d129-4f17-9e4e-cc2d615539d7",
      "credentials": { "secret": "65ca03bd-eb6b-420b-9d5d-46d459d4f71c" },
      "created_at": "2023-06-15T09:05:06.53817Z",
      "updated_at": "0001-01-01T00:00:00Z",
      "status": "enabled"
    },
    {
      "id": "19f59b2d-1e9c-43db-bc84-5432bd52a83f",
      "name": "Motion Sensor",
      "owner": "94939159-d129-4f17-9e4e-cc2d615539d7",
      "credentials": { "secret": "941c380a-3a41-40e9-8b79-3087daa4f3a6" },
      "created_at": "2023-06-15T09:05:45.719182Z",
      "updated_at": "0001-01-01T00:00:00Z",
      "status": "enabled"
    },
    {
      "id": "3709f2b0-9c73-413f-992e-7f6f9b396b0d",
      "name": "Light Sensor",
      "owner": "94939159-d129-4f17-9e4e-cc2d615539d7",
      "credentials": { "secret": "798ee6be-311b-4640-99e4-0ccb19e0dcb9" },
      "created_at": "2023-06-15T09:05:45.719186Z",
      "updated_at": "0001-01-01T00:00:00Z",
      "status": "enabled"
    },
    {
      "id": "eb2670ba-a2be-4ea4-83cb-111111111111",
      "name": "Motion Sensor",
      "owner": "94939159-d129-4f17-9e4e-cc2d615539d7",
      "credentials": { "secret": "325cda17-3a52-465d-89a7-2b63c7d0e3a6" },
      "created_at": "2023-06-15T09:06:17.967825Z",
      "updated_at": "0001-01-01T00:00:00Z",
      "status": "enabled"
    },
    {
      "id": "eb2670ba-a2be-4ea4-83cb-111111111112",
      "name": "Light Sensor",
      "owner": "94939159-d129-4f17-9e4e-cc2d615539d7",
      "credentials": { "secret": "67b6cbb8-4a9e-4d32-8b9c-d7cd3352aa2b" },
      "created_at": "2023-06-15T09:06:17.967828Z",
      "updated_at": "0001-01-01T00:00:00Z",
      "status": "enabled"
    }
  ]
}

If you want to paginate your results then use offset, limit, metadata, name, status, tags and visibility as query parameters.

curl -sSiX GET http://localhost/things?[offset=<offset>]&[limit=<limit>]&name=[name]&[status=<status>] -H "Authorization: Bearer <user_token>"

For example:

curl -sSiX GET http://localhost/things?offset=1&limit=5&name=Light Sensor -H "Authorization: Bearer <user_token>"

HTTP/1.1 200 OK
Server: nginx/1.23.3
Date: Thu, 15 Jun 2023 09:08:39 GMT
Content-Type: application/json
Content-Length: 321
Connection: keep-alive
Access-Control-Expose-Headers: Location

{
  "limit": 5,
  "offset": 1,
  "total": 2,
  "things": [
    {
      "id": "eb2670ba-a2be-4ea4-83cb-111111111112",
      "name": "Light Sensor",
      "owner": "94939159-d129-4f17-9e4e-cc2d615539d7",
      "credentials": { "secret": "67b6cbb8-4a9e-4d32-8b9c-d7cd3352aa2b" },
      "created_at": "2023-06-15T09:06:17.967828Z",
      "updated_at": "0001-01-01T00:00:00Z",
      "status": "enabled"
    }
  ]
}

Update Thing​

Updating a thing name and/or metadata

curl -sSiX PATCH http://localhost/things/<thing_id> -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
{
  "name":"[thing_name]",
  "metadata": {
      "[key1]": "[value1]",
      "[key2]": "[value2]"
  }
}
EOF

For example:

curl -sSiX PATCH http://localhost/things/48101ecd-1535-40c6-9ed8-5b1d21e371bb -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
{
  "name":"Pressure Sensor"
}
EOF

HTTP/1.1 200 OK
Server: nginx/1.23.3
Date: Thu, 15 Jun 2023 09:09:12 GMT
Content-Type: application/json
Content-Length: 332
Connection: keep-alive
Access-Control-Expose-Headers: Location

{
  "id": "48101ecd-1535-40c6-9ed8-5b1d21e371bb",
  "name": "Pressure Sensor",
  "owner": "94939159-d129-4f17-9e4e-cc2d615539d7",
  "credentials": { "secret": "c3f8c096-c60f-4375-8494-bca20a12fca7" },
  "created_at": "2023-06-15T09:04:04.292602Z",
  "updated_at": "2023-06-15T09:09:12.267074Z",
  "updated_by": "94939159-d129-4f17-9e4e-cc2d615539d7",
  "status": "enabled"
}

Update Thing Tags​

Updating a thing tags

curl -sSiX PATCH http://localhost/things/<thing_id>/tags -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
{
  "tags": ["tag_1", ..., "tag_N"]
}
EOF

For example:

curl -sSiX PATCH http://localhost/things/48101ecd-1535-40c6-9ed8-5b1d21e371bb/tags -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
{
  "tags": ["sensor", "smart"]
}
EOF

HTTP/1.1 200 OK
Server: nginx/1.23.3
Date: Thu, 15 Jun 2023 09:09:44 GMT
Content-Type: application/json
Content-Length: 347
Connection: keep-alive
Access-Control-Expose-Headers: Location

{
  "id": "48101ecd-1535-40c6-9ed8-5b1d21e371bb",
  "name": "Pressure Sensor",
  "tags": ["sensor", "smart"],
  "owner": "94939159-d129-4f17-9e4e-cc2d615539d7",
  "credentials": { "secret": "c3f8c096-c60f-4375-8494-bca20a12fca7" },
  "created_at": "2023-06-15T09:04:04.292602Z",
  "updated_at": "2023-06-15T09:09:44.766726Z",
  "updated_by": "94939159-d129-4f17-9e4e-cc2d615539d7",
  "status": "enabled"
}

Update Thing Owner​

Updating a thing entity

curl -sSiX PATCH http://localhost/things/<thing_id>/owner -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
{
  "owner": "[owner_id]"
}
EOF

For example:

curl -sSiX PATCH http://localhost/things/48101ecd-1535-40c6-9ed8-5b1d21e371bb/owner -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
{
  "owner": "f7c55a1f-dde8-4880-9796-b3a0cd05745b"
}
EOF

HTTP/1.1 200 OK
Server: nginx/1.23.3
Date: Thu, 15 Jun 2023 09:09:44 GMT
Content-Type: application/json
Content-Length: 347
Connection: keep-alive
Access-Control-Expose-Headers: Location

{
  "id": "48101ecd-1535-40c6-9ed8-5b1d21e371bb",
  "name": "Pressure Sensor",
  "tags": ["sensor", "smart"],
  "owner": "f7c55a1f-dde8-4880-9796-b3a0cd05745b",
  "credentials": { "secret": "c3f8c096-c60f-4375-8494-bca20a12fca7" },
  "created_at": "2023-06-15T09:04:04.292602Z",
  "updated_at": "2023-06-15T09:09:44.766726Z",
  "updated_by": "94939159-d129-4f17-9e4e-cc2d615539d7",
  "status": "enabled"
}

Update Thing Secret​

Updating a thing secret

curl -sSiX PATCH http://localhost/things/<thing_id>/secret -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
{
  "secret": "<thing_secret>"
}
EOF

For example:

curl -sSiX PATCH http://localhost/things/48101ecd-1535-40c6-9ed8-5b1d21e371bb/secret -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
{
  "secret": "94939159-9a08-4f17-9e4e-3b91cf2ccd3e"
}
EOF

HTTP/1.1 200 OK
Server: nginx/1.23.3
Date: Thu, 15 Jun 2023 09:10:52 GMT
Content-Type: application/json
Content-Length: 321
Connection: keep-alive
Access-Control-Expose-Headers: Location

{
  "id": "48101ecd-1535-40c6-9ed8-5b1d21e371bb",
  "name": "Pressure Sensor",
  "tags": ["sensor", "smart"],
  "owner": "94939159-d129-4f17-9e4e-cc2d615539d7",
  "credentials": { "secret": "94939159-9a08-4f17-9e4e-3b91cf2ccd3e" },
  "created_at": "2023-06-15T09:04:04.292602Z",
  "updated_at": "2023-06-15T09:10:52.051497Z",
  "updated_by": "94939159-d129-4f17-9e4e-cc2d615539d7",
  "status": "enabled"
}

Enable Thing​

To enable a thing you need a thing_id and a user_token

curl -sSiX POST http://localhost/things/<thing_id>/enable -H "Content-Type: application/json" -H  "Authorization: Bearer <user_token>"

For example:

curl -sSiX POST http://localhost/things/48101ecd-1535-40c6-9ed8-5b1d21e371bb/enable -H "Content-Type: application/json" -H  "Authorization: Bearer <user_token>"

HTTP/1.1 200 OK
Server: nginx/1.23.3
Date: Thu, 15 Jun 2023 09:11:43 GMT
Content-Type: application/json
Content-Length: 321
Connection: keep-alive
Access-Control-Expose-Headers: Location

{
  "id": "48101ecd-1535-40c6-9ed8-5b1d21e371bb",
  "name": "Pressure Sensor",
  "tags": ["sensor", "smart"],
  "owner": "94939159-d129-4f17-9e4e-cc2d615539d7",
  "credentials": { "secret": "94939159-9a08-4f17-9e4e-3b91cf2ccd3e" },
  "created_at": "2023-06-15T09:04:04.292602Z",
  "updated_at": "2023-06-15T09:10:52.051497Z",
  "updated_by": "94939159-d129-4f17-9e4e-cc2d615539d7",
  "status": "enabled"
}

Disable Thing​

To disable a thing you need a thing_id and a user_token

curl -sSiX POST http://localhost/things/<thing_id>/disable  -H "Content-Type: application/json" -H  "Authorization: Bearer <user_token>"

For example:

curl -sSiX POST http://localhost/things/48101ecd-1535-40c6-9ed8-5b1d21e371bb/disable  -H "Content-Type: application/json" -H  "Authorization: Bearer <user_token>"

HTTP/1.1 200 OK
Server: nginx/1.23.3
Date: Thu, 15 Jun 2023 09:11:38 GMT
Content-Type: application/json
Content-Length: 322
Connection: keep-alive
Access-Control-Expose-Headers: Location

{
  "id": "48101ecd-1535-40c6-9ed8-5b1d21e371bb",
  "name": "Pressure Sensor",
  "tags": ["sensor", "smart"],
  "owner": "94939159-d129-4f17-9e4e-cc2d615539d7",
  "credentials": { "secret": "94939159-9a08-4f17-9e4e-3b91cf2ccd3e" },
  "created_at": "2023-06-15T09:04:04.292602Z",
  "updated_at": "2023-06-15T09:10:52.051497Z",
  "updated_by": "94939159-d129-4f17-9e4e-cc2d615539d7",
  "status": "disabled"
}

Channels​

Create Channel​

To create a channel, you need a user_token

curl -sSiX POST http://localhost/channels -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
{
  "id": "[channel_id]",
  "name":"[channel_name]",
  "description":"[channel_description]",
  "owner_id": "[owner_id]",
  "metadata": {
      "[key1]": "[value1]",
      "[key2]": "[value2]"
  },
  "status": "[enabled|disabled]"
}
EOF

For example:

curl -sSiX POST http://localhost/channels -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
{
  "name": "Temperature Data"
}
EOF

HTTP/1.1 201 Created
Server: nginx/1.23.3
Date: Thu, 15 Jun 2023 09:12:51 GMT
Content-Type: application/json
Content-Length: 218
Connection: keep-alive
Location: /channels/aecf0902-816d-4e38-a5b3-a1ad9a7cf9e8
Access-Control-Expose-Headers: Location

{
  "id": "aecf0902-816d-4e38-a5b3-a1ad9a7cf9e8",
  "owner_id": "94939159-d129-4f17-9e4e-cc2d615539d7",
  "name": "Temperature Data",
  "created_at": "2023-06-15T09:12:51.162431Z",
  "updated_at": "0001-01-01T00:00:00Z",
  "status": "enabled"
}

Create Channel with external ID​

Channel is a group of things that could represent a special category in existing systems, e.g. a building level channel could represent the level of a smarting building system. For helping to keep the reference, it is possible to set an existing ID while creating the SuperMQ channel. There are two limitations - the existing ID has to be in UUID V4 format and it has to be unique in the SuperMQ domain.

To create a channel with external ID, the user needs to provide a UUID v4 format unique ID, and a user_token

For example:

curl -sSiX POST http://localhost/channels -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
{
  "id": "48101ecd-1535-40c6-9ed8-5b1d21e371bb",
  "name": "Humidity Data"
}
EOF

HTTP/1.1 201 Created
Server: nginx/1.23.3
Date: Thu, 15 Jun 2023 09:15:11 GMT
Content-Type: application/json
Content-Length: 219
Connection: keep-alive
Location: /channels/48101ecd-1535-40c6-9ed8-5b1d21e371bb
Access-Control-Expose-Headers: Location

{
  "id": "48101ecd-1535-40c6-9ed8-5b1d21e371bb",
  "owner_id": "94939159-d129-4f17-9e4e-cc2d615539d7",
  "name": "Humidity Data",
  "created_at": "2023-06-15T09:15:11.477695Z",
  "updated_at": "0001-01-01T00:00:00Z",
  "status": "enabled"
}

Create Channels​

The same as creating a channel with external ID the user can create multiple channels at once by providing UUID v4 format unique ID in a series of channels together with a user_token

curl -sSiX POST http://localhost/channels/bulk -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
[
  {
    "id": "[channel_id]",
    "name":"[channel_name]",
    "description":"[channel_description]",
    "owner_id": "[owner_id]",
    "metadata": {
        "[key1]": "[value1]",
        "[key2]": "[value2]"
    },
    "status": "[enabled|disabled]"
  },
  {
    "id": "[channel_id]",
    "name":"[channel_name]",
    "description":"[channel_description]",
    "owner_id": "[owner_id]",
    "metadata": {
        "[key1]": "[value1]",
        "[key2]": "[value2]"
    },
    "status": "[enabled|disabled]"
  }
]
EOF

For example:

curl -sSiX POST http://localhost/channels/bulk -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
[
  {
    "name":"Light Data"
  },
  {
    "name":"Pressure Data"
  }
]
EOF

HTTP/1.1 200 OK
Server: nginx/1.23.3
Date: Thu, 15 Jun 2023 09:15:44 GMT
Content-Type: application/json
Content-Length: 450
Connection: keep-alive
Access-Control-Expose-Headers: Location

{
  "channels": [
    {
      "id": "cb81bbff-850d-471f-bd74-c15d6e1a6c4e",
      "owner_id": "94939159-d129-4f17-9e4e-cc2d615539d7",
      "name": "Light Data",
      "created_at": "2023-06-15T09:15:44.154283Z",
      "updated_at": "0001-01-01T00:00:00Z",
      "status": "enabled"
    },
    {
      "id": "fc9bf029-b1d3-4408-8d53-fc576247a4b3",
      "owner_id": "94939159-d129-4f17-9e4e-cc2d615539d7",
      "name": "Pressure Data",
      "created_at": "2023-06-15T09:15:44.15721Z",
      "updated_at": "0001-01-01T00:00:00Z",
      "status": "enabled"
    }
  ]
}

Create Channels with external ID​

As with things, you can create multiple channels with external ID at once

For example:

curl -sSiX POST http://localhost/channels/bulk -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
[
  {
    "id": "977bbd33-5b59-4b7a-a9c3-111111111111",
    "name":"Light Data"
  },
  {
    "id": "977bbd33-5b59-4b7a-a9c3-111111111112",
    "name":"Pressure Data"
  }
]
EOF

HTTP/1.1 200 OK
Server: nginx/1.23.3
Date: Thu, 15 Jun 2023 09:16:16 GMT
Content-Type: application/json
Content-Length: 453
Connection: keep-alive
Access-Control-Expose-Headers: Location

{
  "channels": [
    {
      "id": "977bbd33-5b59-4b7a-a9c3-111111111111",
      "owner_id": "94939159-d129-4f17-9e4e-cc2d615539d7",
      "name": "Light Data",
      "created_at": "2023-06-15T09:16:16.931016Z",
      "updated_at": "0001-01-01T00:00:00Z",
      "status": "enabled"
    },
    {
      "id": "977bbd33-5b59-4b7a-a9c3-111111111112",
      "owner_id": "94939159-d129-4f17-9e4e-cc2d615539d7",
      "name": "Pressure Data",
      "created_at": "2023-06-15T09:16:16.934486Z",
      "updated_at": "0001-01-01T00:00:00Z",
      "status": "enabled"
    }
  ]
}

Get Channel​

Get a channel entity for a logged-in user

curl -sSiX GET http://localhost/channels/<channel_id> -H "Authorization: Bearer <user_token>"

For example:

curl -sSiX GET http://localhost/channels/aecf0902-816d-4e38-a5b3-a1ad9a7cf9e8 -H "Authorization: Bearer <user_token>"

HTTP/1.1 200 OK
Server: nginx/1.23.3
Date: Thu, 15 Jun 2023 09:17:17 GMT
Content-Type: application/json
Content-Length: 218
Connection: keep-alive
Access-Control-Expose-Headers: Location

{
  "id": "aecf0902-816d-4e38-a5b3-a1ad9a7cf9e8",
  "owner_id": "94939159-d129-4f17-9e4e-cc2d615539d7",
  "name": "Temperature Data",
  "created_at": "2023-06-15T09:12:51.162431Z",
  "updated_at": "0001-01-01T00:00:00Z",
  "status": "enabled"
}

Get Channels​

You can get all channels for a logged-in user.

If you want to paginate your results then use offset, limit, metadata, name, status, parentID, ownerID, tree and dir as query parameters.

curl -sSiX GET http://localhost/channels -H "Authorization: Bearer <user_token>"

For example:

curl -sSiX GET http://localhost/channels -H "Authorization: Bearer <user_token>"

HTTP/1.1 200 OK
Server: nginx/1.23.3
Date: Thu, 15 Jun 2023 09:17:46 GMT
Content-Type: application/json
Content-Length: 1754
Connection: keep-alive
Access-Control-Expose-Headers: Location

{
  "total": 8,
  "channels": [
    {
      "id": "17129934-4f48-4163-bffe-0b7b532edc5c",
      "owner_id": "94939159-d129-4f17-9e4e-cc2d615539d7",
      "name": "Tokyo",
      "created_at": "2023-06-14T12:10:07.950311Z",
      "updated_at": "0001-01-01T00:00:00Z",
      "status": "enabled"
    },
    {
      "id": "48101ecd-1535-40c6-9ed8-5b1d21e371bb",
      "owner_id": "94939159-d129-4f17-9e4e-cc2d615539d7",
      "name": "Humidity Data",
      "created_at": "2023-06-15T09:15:11.477695Z",
      "updated_at": "0001-01-01T00:00:00Z",
      "status": "enabled"
    },
    {
      "id": "977bbd33-5b59-4b7a-a9c3-111111111111",
      "owner_id": "94939159-d129-4f17-9e4e-cc2d615539d7",
      "name": "Light Data",
      "created_at": "2023-06-15T09:16:16.931016Z",
      "updated_at": "0001-01-01T00:00:00Z",
      "status": "enabled"
    },
    {
      "id": "977bbd33-5b59-4b7a-a9c3-111111111112",
      "owner_id": "94939159-d129-4f17-9e4e-cc2d615539d7",
      "name": "Pressure Data",
      "created_at": "2023-06-15T09:16:16.934486Z",
      "updated_at": "0001-01-01T00:00:00Z",
      "status": "enabled"
    },
    {
      "id": "aecf0902-816d-4e38-a5b3-a1ad9a7cf9e8",
      "owner_id": "94939159-d129-4f17-9e4e-cc2d615539d7",
      "name": "Temperature Data",
      "created_at": "2023-06-15T09:12:51.162431Z",
      "updated_at": "0001-01-01T00:00:00Z",
      "status": "enabled"
    },
    {
      "id": "b3867a52-675d-4f05-8cd0-df5a08a63ff3",
      "owner_id": "94939159-d129-4f17-9e4e-cc2d615539d7",
      "name": "London",
      "created_at": "2023-06-14T12:09:34.205894Z",
      "updated_at": "0001-01-01T00:00:00Z",
      "status": "enabled"
    },
    {
      "id": "cb81bbff-850d-471f-bd74-c15d6e1a6c4e",
      "owner_id": "94939159-d129-4f17-9e4e-cc2d615539d7",
      "name": "Light Data",
      "created_at": "2023-06-15T09:15:44.154283Z",
      "updated_at": "0001-01-01T00:00:00Z",
      "status": "enabled"
    },
    {
      "id": "fc9bf029-b1d3-4408-8d53-fc576247a4b3",
      "owner_id": "94939159-d129-4f17-9e4e-cc2d615539d7",
      "name": "Pressure Data",
      "created_at": "2023-06-15T09:15:44.15721Z",
      "updated_at": "0001-01-01T00:00:00Z",
      "status": "enabled"
    }
  ]
}

Update Channel​

Update channel name and/or metadata.

curl -sSiX PUT http://localhost/channels/<channel_id> -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
{
  "name":"[channel_name]",
  "description":"[channel_description]",
  "metadata": {
      "[key1]": "[value1]",
      "[key2]": "[value2]"
  }
}
EOF

For example:

curl -sSiX PUT http://localhost/channels/aecf0902-816d-4e38-a5b3-a1ad9a7cf9e8 -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
{
  "name":"Jane Doe",
  "metadata": {
      "location": "london"
  }
}
EOF

HTTP/1.1 200 OK
Server: nginx/1.23.3
Date: Thu, 15 Jun 2023 09:18:26 GMT
Content-Type: application/json
Content-Length: 296
Connection: keep-alive
Access-Control-Expose-Headers: Location

{
  "id": "aecf0902-816d-4e38-a5b3-a1ad9a7cf9e8",
  "owner_id": "94939159-d129-4f17-9e4e-cc2d615539d7",
  "name": "Jane Doe",
  "metadata": { "location": "london" },
  "created_at": "2023-06-15T09:12:51.162431Z",
  "updated_at": "2023-06-15T09:18:26.886913Z",
  "updated_by": "94939159-d129-4f17-9e4e-cc2d615539d7",
  "status": "enabled"
}

Enable Channel​

To enable a channel you need a channel_id and a user_token

curl -sSiX POST http://localhost/channels/<channel_id>/enable -H "Content-Type: application/json" -H  "Authorization: Bearer <user_token>"

For example:

curl -sSiX POST http://localhost/channels/aecf0902-816d-4e38-a5b3-a1ad9a7cf9e8/enable -H "Content-Type: application/json" -H  "Authorization: Bearer <user_token>"

HTTP/1.1 200 OK
Server: nginx/1.23.3
Date: Thu, 15 Jun 2023 09:19:29 GMT
Content-Type: application/json
Content-Length: 296
Connection: keep-alive
Access-Control-Expose-Headers: Location

{
  "id": "aecf0902-816d-4e38-a5b3-a1ad9a7cf9e8",
  "owner_id": "94939159-d129-4f17-9e4e-cc2d615539d7",
  "name": "Jane Doe",
  "metadata": { "location": "london" },
  "created_at": "2023-06-15T09:12:51.162431Z",
  "updated_at": "2023-06-15T09:18:26.886913Z",
  "updated_by": "94939159-d129-4f17-9e4e-cc2d615539d7",
  "status": "enabled"
}

Disable Channel​

To disable a channel you need a channel_id and a user_token

curl -sSiX POST http://localhost/channels/<channel_id>/disable -H "Content-Type: application/json" -H  "Authorization: Bearer <user_token>"

For example:

curl -sSiX POST http://localhost/channels/aecf0902-816d-4e38-a5b3-a1ad9a7cf9e8/disable -H "Content-Type: application/json" -H  "Authorization: Bearer <user_token>"

HTTP/1.1 200 OK
Server: nginx/1.23.3
Date: Thu, 15 Jun 2023 09:19:24 GMT
Content-Type: application/json
Content-Length: 297
Connection: keep-alive
Access-Control-Expose-Headers: Location

{
  "id": "aecf0902-816d-4e38-a5b3-a1ad9a7cf9e8",
  "owner_id": "94939159-d129-4f17-9e4e-cc2d615539d7",
  "name": "Jane Doe",
  "metadata": { "location": "london" },
  "created_at": "2023-06-15T09:12:51.162431Z",
  "updated_at": "2023-06-15T09:18:26.886913Z",
  "updated_by": "94939159-d129-4f17-9e4e-cc2d615539d7",
  "status": "disabled"
}

Connect​

Connect things to channels

actions is optional, if not provided, the default action is m_read and m_write.

curl -sSiX POST http://localhost/connect -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
{
  "subjects": ["<thing_id>"],
  "objects": ["<channel_id>"],
  "actions": ["[action]"]
}
EOF

For example:

curl -sSiX POST http://localhost/connect -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
{
  "subjects": ["48101ecd-1535-40c6-9ed8-5b1d21e371bb"],
  "objects": ["aecf0902-816d-4e38-a5b3-a1ad9a7cf9e8"]
}
EOF

HTTP/1.1 201 Created
Server: nginx/1.23.3
Date: Thu, 15 Jun 2023 09:21:37 GMT
Content-Type: application/json
Content-Length: 247
Connection: keep-alive
Access-Control-Expose-Headers: Location

{
  "policies": [
    {
      "owner_id": "",
      "subject": "48101ecd-1535-40c6-9ed8-5b1d21e371bb",
      "object": "aecf0902-816d-4e38-a5b3-a1ad9a7cf9e8",
      "actions": ["m_write", "m_read"],
      "created_at": "0001-01-01T00:00:00Z",
      "updated_at": "0001-01-01T00:00:00Z",
      "updated_by": ""
    }
  ]
}

Connect thing to channel

actions is optional, if not provided, the default actions are m_read and m_write.

curl -sSiX POST http://localhost/things/policies -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
{
  "subject": "<thing_id>",
  "object": "<channel_id>",
  "actions": ["<action>", "[action]"]]
}
EOF

For example:

curl -sSiX POST http://localhost/things/policies -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
{
  "subject": "48101ecd-1535-40c6-9ed8-5b1d21e371bb",
  "object": "aecf0902-816d-4e38-a5b3-a1ad9a7cf9e8"
}
EOF

HTTP/1.1 201 Created
Server: nginx/1.23.3
Date: Thu, 15 Jun 2023 09:23:28 GMT
Content-Type: application/json
Content-Length: 290
Connection: keep-alive
Access-Control-Expose-Headers: Location

{
  "policies": [
    {
      "owner_id": "94939159-d129-4f17-9e4e-cc2d615539d7",
      "subject": "48101ecd-1535-40c6-9ed8-5b1d21e371bb",
      "object": "aecf0902-816d-4e38-a5b3-a1ad9a7cf9e8",
      "actions": ["m_write", "m_read"],
      "created_at": "2023-06-15T09:23:28.769729Z",
      "updated_at": "0001-01-01T00:00:00Z",
      "updated_by": ""
    }
  ]
}

Disconnect​

Disconnect things from channels specified by lists of IDs.

curl -sSiX POST http://localhost/disconnect -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
{
  "subjects": ["<thing_id_1>", "[thing_id_2]"],
  "objects": ["<channel_id_1>", "[channel_id_2]"]
}
EOF

For example:

curl -sSiX POST http://localhost/disconnect -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
{
  "subjects": ["48101ecd-1535-40c6-9ed8-5b1d21e371bb"],
  "objects": ["aecf0902-816d-4e38-a5b3-a1ad9a7cf9e8"]
}
EOF

HTTP/1.1 204 No Content
Server: nginx/1.23.3
Date: Thu, 15 Jun 2023 09:23:07 GMT
Content-Type: application/json
Connection: keep-alive
Access-Control-Expose-Headers: Location

Disconnect thing from the channel

curl -sSiX DELETE http://localhost/things/policies/<subject_id>/<object_id> -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>"

For example:

curl -sSiX DELETE http://localhost/things/policies/48101ecd-1535-40c6-9ed8-5b1d21e371bb/aecf0902-816d-4e38-a5b3-a1ad9a7cf9e8 -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>"

HTTP/1.1 204 No Content
Server: nginx/1.23.3
Date: Thu, 15 Jun 2023 09:25:23 GMT
Content-Type: application/json
Connection: keep-alive
Access-Control-Expose-Headers: Location

Access by Key​

Checks if thing has access to a channel

curl -sSiX POST http://localhost/channels/<channel_id>/access -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
{
  "subject": "<thing_secret>",
  "action": "m_read" | "m_write",
  "entity_type": "thing"
}
EOF

For example:

curl -sSiX POST http://localhost/channels/aecf0902-816d-4e38-a5b3-a1ad9a7cf9e8/access -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
{
  "subject": "48101ecd-1535-40c6-9ed8-5b1d21e371bb",
  "action": "m_read",
  "entity_type": "thing"
}
EOF

HTTP/1.1 200 OK
Server: nginx/1.23.3
Date: Thu, 15 Jun 2023 09:39:26 GMT
Content-Type: application/json
Content-Length: 0
Connection: keep-alive
Access-Control-Expose-Headers: Location

Identify​

Validates thing's key and returns it's ID if key is valid

curl -sSiX POST http://localhost/identify -H "Content-Type: application/json" -H "Authorization: Thing <thing_secret>"

For example:

curl -sSiX POST http://localhost/identify -H "Content-Type: application/json" -H "Authorization: Thing 6d11a91f-0bd8-41aa-8e1b-4c6338329c9c"

HTTP/1.1 200 OK
Server: nginx/1.23.3
Date: Thu, 15 Jun 2023 09:28:16 GMT
Content-Type: application/json
Content-Length: 46
Connection: keep-alive
Access-Control-Expose-Headers: Location

{ "id": "f3047c10-f2c7-4d53-b3c0-bc56c560c546" }

Messages​

Send Messages​

Sends message via HTTP protocol

curl -sSiX POST http://localhost/http/channels/<channel_id>/messages -H "Content-Type: application/senml+json" -H "Authorization: Thing <thing_secret>" -d @- << EOF
[
  {
    "bn": "<base_name>",
    "bt": "[base_time]",
    "bu": "[base_unit]",
    "bver": [base_version],
    "n": "<measurement_name>",
    "u": "<measurement_unit>",
    "v": <measurement_value>,
  },
  {
    "n": "[measurement_name]",
    "t": <measurement_time>,
    "v": <measurement_value>,
  }
]
EOF

For example:

curl -sSiX POST http://localhost/http/channels/aecf0902-816d-4e38-a5b3-a1ad9a7cf9e8/messages -H "Content-Type: application/senml+json" -H "Authorization: Thing a83b9afb-9022-4f9e-ba3d-4354a08c273a" -d @- << EOF
[
  {
    "bn": "some-base-name:",
    "bt": 1.276020076001e+09,
    "bu": "A",
    "bver": 5,
    "n": "voltage",
    "u": "V",
    "v": 120.1
  },
  {
    "n": "current",
    "t": -5,
    "v": 1.2
  },
  {
    "n": "current",
    "t": -4,
    "v": 1.3
  }
]
EOF
HTTP/1.1 202 Accepted
Server: nginx/1.23.3
Date: Thu, 15 Jun 2023 09:40:44 GMT
Content-Length: 0
Connection: keep-alive

Read Messages​

Reads messages from database for a given channel

curl -sSiX GET http://localhost:<service_port>/channels/<channel_id>/messages?[offset=<offset>]&[limit=<limit>] -H "Authorization: Thing <thing_secret>"

For example:

curl -sSiX GET http://localhost:9009/channels/aecf0902-816d-4e38-a5b3-a1ad9a7cf9e8/messages -H "Authorization: Thing a83b9afb-9022-4f9e-ba3d-4354a08c273a"

HTTP/1.1 200 OK
Content-Type: application/json
Date: Wed, 05 Apr 2023 16:01:49 GMT
Content-Length: 660

{
    "offset": 0,
    "limit": 10,
    "format": "messages",
    "total": 3,
    "messages": [{
            "channel": "aecf0902-816d-4e38-a5b3-a1ad9a7cf9e8",
            "publisher": "2766ae94-9a08-4418-82ce-3b91cf2ccd3e",
            "protocol": "http",
            "name": "some-base-name:voltage",
            "unit": "V",
            "time": 1276020076.001,
            "value": 120.1
        },
        {
            "channel": "aecf0902-816d-4e38-a5b3-a1ad9a7cf9e8",
            "publisher": "2766ae94-9a08-4418-82ce-3b91cf2ccd3e",
            "protocol": "http",
            "name": "some-base-name:current",
            "unit": "A",
            "time": 1276020072.001,
            "value": 1.3
        },
        {
            "channel": "aecf0902-816d-4e38-a5b3-a1ad9a7cf9e8",
            "publisher": "2766ae94-9a08-4418-82ce-3b91cf2ccd3e",
            "protocol": "http",
            "name": "some-base-name:current",
            "unit": "A",
            "time": 1276020071.001,
            "value": 1.2
        }
    ]
}

Groups​

Create group​

To create a group, you need the group name and a user_token

curl -sSiX POST http://localhost/groups -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
{
  "name":"<group_name>",
  "description":"[group_description]",
  "parent_id": "[parent_id]",
  "owner_id": "[owner_id]",
  "metadata": {
      "[key1]": "[value1]",
      "[key2]": "[value2]"
  },
  "status": "[enabled|disabled]"
}
EOF

For example:

curl -sSiX POST http://localhost/groups -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
{
  "name": "Security Engineers",
  "description": "This group would be responsible for securing the platform."
}
EOF

HTTP/1.1 201 Created
Server: nginx/1.23.3
Date: Thu, 15 Jun 2023 09:41:42 GMT
Content-Type: application/json
Content-Length: 252
Connection: keep-alive
Location: /groups/2766ae94-9a08-4418-82ce-3b91cf2ccd3e
Access-Control-Expose-Headers: Location

{
  "id": "2766ae94-9a08-4418-82ce-3b91cf2ccd3e",
  "owner_id": "94939159-d129-4f17-9e4e-cc2d615539d7",
  "name": "Security Engineers",
  "description": "This group would be responsible for securing the platform.",
  "created_at": "2023-06-15T09:41:42.860481Z",
  "updated_at": "0001-01-01T00:00:00Z",
  "status": "enabled"
}

When you use parent_id make sure the parent is an already exisiting group

For example:

curl -sSiX POST http://localhost/groups -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
{
  "name": "Customer Support",
  "description": "This group would be responsible for providing support to users of the platform.",
  "parent_id": "2766ae94-9a08-4418-82ce-3b91cf2ccd3e"
}
EOF

HTTP/1.1 201 Created
Server: nginx/1.23.3
Date: Thu, 15 Jun 2023 09:42:34 GMT
Content-Type: application/json
Content-Length: 306
Connection: keep-alive
Location: /groups/dd2dc8d4-f7cf-42f9-832b-81cae9a8e90a
Access-Control-Expose-Headers: Location

{
  "id": "dd2dc8d4-f7cf-42f9-832b-81cae9a8e90a",
  "owner_id": "94939159-d129-4f17-9e4e-cc2d615539d7",
  "parent_id": "2766ae94-9a08-4418-82ce-3b91cf2ccd3e",
  "name": "Customer Support",
  "description": "This group would be responsible for providing support to users of the platform.",
  "created_at": "2023-06-15T09:42:34.063997Z",
  "updated_at": "0001-01-01T00:00:00Z",
  "status": "enabled"
}

Get group​

Get a group entity for a logged-in user

curl -sSiX GET http://localhost/groups/<group_id> -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>"

For example:

curl -sSiX GET http://localhost/groups/2766ae94-9a08-4418-82ce-3b91cf2ccd3e -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>"

HTTP/1.1 200 OK
Server: nginx/1.23.3
Date: Thu, 15 Jun 2023 10:00:52 GMT
Content-Type: application/json
Content-Length: 252
Connection: keep-alive
Access-Control-Expose-Headers: Location

{
  "id": "2766ae94-9a08-4418-82ce-3b91cf2ccd3e",
  "owner_id": "94939159-d129-4f17-9e4e-cc2d615539d7",
  "name": "Security Engineers",
  "description": "This group would be responsible for securing the platform.",
  "created_at": "2023-06-15T09:41:42.860481Z",
  "updated_at": "0001-01-01T00:00:00Z",
  "status": "enabled"
}

Get groups​

You can get all groups for a logged-in user.

If you want to paginate your results then use offset, limit, metadata, name, status, parentID, ownerID, tree and dir as query parameters.

curl -sSiX GET http://localhost/groups -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>"

For example:

curl -sSiX GET http://localhost/groups -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>"

HTTP/1.1 200 OK
Server: nginx/1.23.3
Date: Thu, 15 Jun 2023 10:13:50 GMT
Content-Type: application/json
Content-Length: 807
Connection: keep-alive
Access-Control-Expose-Headers: Location

{
  "limit": 0,
  "offset": 0,
  "total": 3,
  "groups": [
    {
      "id": "0a4a2c33-2d0e-43df-b51c-d905aba99e17",
      "owner_id": "94939159-d129-4f17-9e4e-cc2d615539d7",
      "name": "Sensor Operators",
      "created_at": "2023-06-14T13:33:52.249784Z",
      "updated_at": "0001-01-01T00:00:00Z",
      "status": "enabled"
    },
    {
      "id": "2766ae94-9a08-4418-82ce-3b91cf2ccd3e",
      "owner_id": "94939159-d129-4f17-9e4e-cc2d615539d7",
      "name": "Security Engineers",
      "description": "This group would be responsible for securing the platform.",
      "created_at": "2023-06-15T09:41:42.860481Z",
      "updated_at": "0001-01-01T00:00:00Z",
      "status": "enabled"
    },
    {
      "id": "dd2dc8d4-f7cf-42f9-832b-81cae9a8e90a",
      "owner_id": "94939159-d129-4f17-9e4e-cc2d615539d7",
      "parent_id": "2766ae94-9a08-4418-82ce-3b91cf2ccd3e",
      "name": "Customer Support",
      "description": "This group would be responsible for providing support to users of the platform.",
      "created_at": "2023-06-15T09:42:34.063997Z",
      "updated_at": "0001-01-01T00:00:00Z",
      "status": "enabled"
    }
  ]
}

Get Group Parents​

You can get all groups that are parents of a group for a logged-in user.

If you want to paginate your results then use offset, limit, metadata, name, status, parentID, ownerID, tree and dir as query parameters.

curl -sSiX GET http://localhost/groups/<group_id>/parents -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>"

For example:

curl -sSiX GET http://localhost/groups/dd2dc8d4-f7cf-42f9-832b-81cae9a8e90a/parents?tree=true -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>"

HTTP/1.1 200 OK
Server: nginx/1.23.3
Date: Thu, 15 Jun 2023 10:16:03 GMT
Content-Type: application/json
Content-Length: 627
Connection: keep-alive
Access-Control-Expose-Headers: Location

{
  "limit": 10,
  "offset": 0,
  "total": 3,
  "groups": [
    {
      "id": "2766ae94-9a08-4418-82ce-3b91cf2ccd3e",
      "owner_id": "94939159-d129-4f17-9e4e-cc2d615539d7",
      "name": "Security Engineers",
      "description": "This group would be responsible for securing the platform.",
      "level": -1,
      "children": [
        {
          "id": "dd2dc8d4-f7cf-42f9-832b-81cae9a8e90a",
          "owner_id": "94939159-d129-4f17-9e4e-cc2d615539d7",
          "parent_id": "2766ae94-9a08-4418-82ce-3b91cf2ccd3e",
          "name": "Customer Support",
          "description": "This group would be responsible for providing support to users of the platform.",
          "created_at": "2023-06-15T09:42:34.063997Z",
          "updated_at": "0001-01-01T00:00:00Z",
          "status": "enabled"
        }
      ],
      "created_at": "2023-06-15T09:41:42.860481Z",
      "updated_at": "0001-01-01T00:00:00Z",
      "status": "enabled"
    }
  ]
}

Get Group Children​

You can get all groups that are children of a group for a logged-in user.

If you want to paginate your results then use offset, limit, metadata, name, status, parentID, ownerID, tree and dir as query parameters.

curl -sSiX GET http://localhost/groups/<group_id>/children -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>"

For example:

curl -sSiX GET http://localhost/groups/2766ae94-9a08-4418-82ce-3b91cf2ccd3e/children?tree=true -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>"

HTTP/1.1 200 OK
Server: nginx/1.23.3
Date: Thu, 15 Jun 2023 10:17:13 GMT
Content-Type: application/json
Content-Length: 755
Connection: keep-alive
Access-Control-Expose-Headers: Location

{
  "limit": 10,
  "offset": 0,
  "total": 3,
  "groups": [
    {
      "id": "2766ae94-9a08-4418-82ce-3b91cf2ccd3e",
      "owner_id": "94939159-d129-4f17-9e4e-cc2d615539d7",
      "name": "Security Engineers",
      "description": "This group would be responsible for securing the platform.",
      "path": "2766ae94-9a08-4418-82ce-3b91cf2ccd3e",
      "children": [
        {
          "id": "dd2dc8d4-f7cf-42f9-832b-81cae9a8e90a",
          "owner_id": "94939159-d129-4f17-9e4e-cc2d615539d7",
          "parent_id": "2766ae94-9a08-4418-82ce-3b91cf2ccd3e",
          "name": "Customer Support",
          "description": "This group would be responsible for providing support to users of the platform.",
          "level": 1,
          "path": "2766ae94-9a08-4418-82ce-3b91cf2ccd3e.dd2dc8d4-f7cf-42f9-832b-81cae9a8e90a",
          "created_at": "2023-06-15T09:42:34.063997Z",
          "updated_at": "0001-01-01T00:00:00Z",
          "status": "enabled"
        }
      ],
      "created_at": "2023-06-15T09:41:42.860481Z",
      "updated_at": "0001-01-01T00:00:00Z",
      "status": "enabled"
    }
  ]
}

Update group​

Update group entity

curl -sSiX PUT http://localhost/groups/<group_id> -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
{
  "name":"[group_name]",
  "description":"[group_description]",
  "metadata": {
      "[key1]": "[value1]",
      "[key2]": "[value2]"
  }
}
EOF

For example:

curl -sSiX PUT http://localhost/groups/2766ae94-9a08-4418-82ce-3b91cf2ccd3e  -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
{
  "name":"Data Analysts",
  "description":"This group would be responsible for analyzing data collected from sensors.",
  "metadata": {
      "location": "london"
  }
}
EOF

HTTP/1.1 200 OK
Server: nginx/1.23.3
Date: Thu, 15 Jun 2023 10:17:56 GMT
Content-Type: application/json
Content-Length: 328
Connection: keep-alive
Access-Control-Expose-Headers: Location

{
  "id": "2766ae94-9a08-4418-82ce-3b91cf2ccd3e",
  "owner_id": "94939159-d129-4f17-9e4e-cc2d615539d7",
  "name": "Data Analysts",
  "description": "This group would be responsible for analyzing data collected from sensors.",
  "metadata": { "location": "london" },
  "created_at": "2023-06-15T09:41:42.860481Z",
  "updated_at": "2023-06-15T10:17:56.475241Z",
  "updated_by": "94939159-d129-4f17-9e4e-cc2d615539d7",
  "status": "enabled"
}

Disable group​

Disable a group entity

curl -sSiX POST http://localhost/groups/<group_id>/disable -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>"

For example:

curl -sSiX POST http://localhost/groups/2766ae94-9a08-4418-82ce-3b91cf2ccd3e/disable -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>"

HTTP/1.1 200 OK
Server: nginx/1.23.3
Date: Thu, 15 Jun 2023 10:18:28 GMT
Content-Type: application/json
Content-Length: 329
Connection: keep-alive
Access-Control-Expose-Headers: Location

{
  "id": "2766ae94-9a08-4418-82ce-3b91cf2ccd3e",
  "owner_id": "94939159-d129-4f17-9e4e-cc2d615539d7",
  "name": "Data Analysts",
  "description": "This group would be responsible for analyzing data collected from sensors.",
  "metadata": { "location": "london" },
  "created_at": "2023-06-15T09:41:42.860481Z",
  "updated_at": "2023-06-15T10:17:56.475241Z",
  "updated_by": "94939159-d129-4f17-9e4e-cc2d615539d7",
  "status": "disabled"
}

Enable group​

Enable a group entity

curl -sSiX POST http://localhost/groups/<group_id>/enable -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>"

For example:

curl -sSiX POST http://localhost/groups/2766ae94-9a08-4418-82ce-3b91cf2ccd3e/enable -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>"

HTTP/1.1 200 OK
Server: nginx/1.23.3
Date: Thu, 15 Jun 2023 10:18:55 GMT
Content-Type: application/json
Content-Length: 328
Connection: keep-alive
Access-Control-Expose-Headers: Location

{
  "id": "2766ae94-9a08-4418-82ce-3b91cf2ccd3e",
  "owner_id": "94939159-d129-4f17-9e4e-cc2d615539d7",
  "name": "Data Analysts",
  "description": "This group would be responsible for analyzing data collected from sensors.",
  "metadata": { "location": "london" },
  "created_at": "2023-06-15T09:41:42.860481Z",
  "updated_at": "2023-06-15T10:17:56.475241Z",
  "updated_by": "94939159-d129-4f17-9e4e-cc2d615539d7",
  "status": "enabled"
}

Assign​

Assign user to a group

curl -sSiX POST http://localhost/users/policies -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
{
  "subject": "<user_id>",
  "object": "<group_id>",
  "actions": ["<member_action>"]
}
EOF

For example:

curl -sSiX POST http://localhost/users/policies -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
{
  "subject": "1890c034-7ef9-4cde-83df-d78ea1d4d281",
  "object": "2766ae94-9a08-4418-82ce-3b91cf2ccd3e",
  "actions": ["g_list", "c_list"]
}
EOF

HTTP/1.1 201 Created
Server: nginx/1.23.3
Date: Thu, 15 Jun 2023 10:19:59 GMT
Content-Type: application/json
Content-Length: 0
Connection: keep-alive
Access-Control-Expose-Headers: Location

Members​

You can get all users assigned to a group.

If you want to paginate your results then use offset, limit, metadata, name, status, identity, and tag as query parameters.

Must take into consideration the user identified by the user_token needs to be assigned to the same group identified by group_id with g_list action or be the owner of the group identified by group_id.

curl -sSiX GET http://localhost/groups/<group_id>/members -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>"

For example:

curl -sSiX GET http://localhost/groups/2766ae94-9a08-4418-82ce-3b91cf2ccd3e/members -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>"

HTTP/1.1 200 OK
Server: nginx/1.23.3
Date: Thu, 15 Jun 2023 11:21:29 GMT
Content-Type: application/json
Content-Length: 318
Connection: keep-alive
Access-Control-Expose-Headers: Location

{
  "limit": 10,
  "total": 1,
  "members": [
    {
      "id": "1890c034-7ef9-4cde-83df-d78ea1d4d281",
      "name": "Jane Doe",
      "tags": ["male", "developer"],
      "credentials": { "identity": "updated.jane.doe@gmail.com" },
      "metadata": { "location": "london" },
      "created_at": "2023-06-14T13:46:47.322648Z",
      "updated_at": "2023-06-14T13:59:53.422595Z",
      "status": "enabled"
    }
  ]
}

Unassign​

Unassign user from group

curl -sSiX DELETE http://localhost/users/policies/<subject_id>/<object_id> -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>"

For example:

curl -sSiX DELETE http://localhost/users/policies/1890c034-7ef9-4cde-83df-d78ea1d4d281/2766ae94-9a08-4418-82ce-3b91cf2ccd3e  -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>"

HTTP/1.1 204 No Content
Server: nginx/1.23.3
Date: Thu, 15 Jun 2023 11:25:27 GMT
Content-Type: application/json
Connection: keep-alive
Access-Control-Expose-Headers: Location

Policies​

Add policies​

Only actions defined on Predefined Policies section are allowed.

curl -sSiX POST http://localhost/users/policies -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
{
  "subject": "<user_id>",
  "object": "<group_id>",
  "actions": ["<actions>", "[actions]"]
}
EOF
curl -sSiX POST http://localhost/things/policies -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
{
  "subject": "<thing_id>",
  "object": "<channel_id>",
  "actions": ["<actions>", "[actions]"]
}
EOF
curl -sSiX POST http://localhost/things/policies -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
{
  "subject": "<user_id>",
  "object": "<channel_id>",
  "actions": ["<actions>", "[actions]"]
  "external": true
}
EOF

For example:

curl -sSiX POST http://localhost/users/policies -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
{
  "subject": "1890c034-7ef9-4cde-83df-d78ea1d4d281",
  "object": "2766ae94-9a08-4418-82ce-3b91cf2ccd3e",
  "actions": ["g_add", "c_list"]
}
EOF

HTTP/1.1 201 Created
Server: nginx/1.23.3
Date: Thu, 15 Jun 2023 11:26:50 GMT
Content-Type: application/json
Content-Length: 0
Connection: keep-alive
Access-Control-Expose-Headers: Location

Update policies​

Only actions defined on Predefined Policies section are allowed.

curl -sSiX PUT http://localhost/users/policies -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
{
  "subject": "<user_id>",
  "object": "<group_id>",
  "actions": ["<actions>", "[actions]"]
}
EOF
curl -sSiX PUT http://localhost/things/policies -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
{
  "subject": "<thing_id> | <user_id>",
  "object": "<channel_id>",
  "actions": ["<actions>", "[actions]"]
}
EOF

For example:

curl -sSiX PUT http://localhost/users/policies -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>" -d @- << EOF
{
  "subject": "1890c034-7ef9-4cde-83df-d78ea1d4d281",
  "object": "2766ae94-9a08-4418-82ce-3b91cf2ccd3e",
  "actions": ["g_list", "c_list"]
}
EOF

HTTP/1.1 204 No Content
Server: nginx/1.23.3
Date: Thu, 15 Jun 2023 11:27:19 GMT
Content-Type: application/json
Connection: keep-alive
Access-Control-Expose-Headers: Location

Delete policies​

Only policies defined on Predefined Policies section are allowed.

curl -sSiX DELETE http://localhost/users/policies/<user_id>/<channel_id> -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>"
curl -sSiX DELETE http://localhost/things/policies/<thing_id>/<channel_id> -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>"

For example:

curl -sSiX DELETE http://localhost/users/policies/1890c034-7ef9-4cde-83df-d78ea1d4d281/2766ae94-9a08-4418-82ce-3b91cf2ccd3e -H "Content-Type: application/json" -H "Authorization: Bearer <user_token>"

HTTP/1.1 204 No Content
Server: nginx/1.23.3
Date: Thu, 15 Jun 2023 11:28:31 GMT
Content-Type: application/json
Connection: keep-alive
Access-Control-Expose-Headers: Location