You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The REST API lets you list the roles defined in your IoT Central application. Use the following request to retrieve a list of application role and organization role IDs from your application. To learn more see, [How to manage IoT Central organizations](howto-create-organizations.md):
193
+
194
+
```http
195
+
GET https://{your app subdomain}.azureiotcentral.com/api/roles?api-version=2022-05-31
196
+
```
197
+
198
+
The response to this request looks like the following example that includes the application role and organization role IDs.
199
+
200
+
```json
201
+
{
202
+
"value": [
203
+
{
204
+
"id": "ca310b8d-2f4a-44e0-a36e-957c202cd8d4",
205
+
"displayName": "Administrator"
206
+
},
207
+
{
208
+
"id": "ae2c9854-393b-4f97-8c42-479d70ce626e",
209
+
"displayName": "Operator"
210
+
},
211
+
{
212
+
"id": "344138e9-8de4-4497-8c54-5237e96d6aaf",
213
+
"displayName": "Builder"
214
+
},
215
+
{
216
+
"id": "c495eb57-eb18-489e-9802-62c474e5645c",
217
+
"displayName": "Org Admin"
218
+
},
219
+
{
220
+
"id": "b4935647-30e4-4ed3-9074-dcac66c2f8ef",
221
+
"displayName": "Org Operator"
222
+
},
223
+
{
224
+
"id": "84cc62c1-dabe-49d3-b16e-8b291232b285",
225
+
"displayName": "Org Viewer"
226
+
}
227
+
]
228
+
}
229
+
```
230
+
231
+
### Create an API token to a node in an organization hierarchy
232
+
233
+
Use the following request to create Create an API token to a node in an organization hierarchy in your application:
234
+
235
+
```http
236
+
PUT https://{your app subdomain}.azureiotcentral.com/api/apiTokens/{tokenId}?api-version=2022-05-31
237
+
```
238
+
239
+
* tokenId - Unique ID of the token
240
+
241
+
The following example shows a request body that creates an API token for an organization in a IoT Central application.
242
+
243
+
```json
244
+
{
245
+
"roles": [
246
+
{
247
+
"role": "84cc62c1-dabe-49d3-b16e-8b291232b285",
248
+
"organization": "seattle"
249
+
}
250
+
]
251
+
}
252
+
```
253
+
254
+
The request body has some required fields:
255
+
256
+
|Name|Description|
257
+
|----|-----------|
258
+
|role |ID of one of the organization roles.|
259
+
|organization| ID of the organization|
260
+
261
+
The response to this request looks like the following example:
### Associate a user with a node in an organization hierarchy
278
+
279
+
Use the following request to create and associate a user with a node in an organization hierarchy in your application. The ID and email must be unique in the application:
280
+
281
+
```http
282
+
PUT https://{your app subdomain}.azureiotcentral.com/api/users/user-001?api-version=2022-05-31
283
+
```
284
+
285
+
In the following request body, the `role` is the ID of one of the organization roles and `organization` is the ID of the organization
Use the following request to associate a new device with an organization
321
+
322
+
```http
323
+
PUT https://{your app subdomain}.azureiotcentral.com/api/devices/{deviceId}?api-version=2022-05-31
324
+
```
325
+
326
+
The following example shows a request body that adds a device for a device template. You can get the `template` details from the device templates page in IoT Central application UI.
327
+
328
+
```json
329
+
{
330
+
"displayName": "CheckoutThermostat",
331
+
"template": "dtmi:contoso:Thermostat;1",
332
+
"simulated": true,
333
+
"enabled": true,
334
+
"organizations": [
335
+
"seattle"
336
+
]
337
+
}
338
+
```
339
+
340
+
The request body has some required fields:
341
+
342
+
*`@displayName`: Display name of the device.
343
+
*`@enabled`: declares that this object is an interface.
344
+
*`@etag`: ETag used to prevent conflict in device updates.
345
+
*`simulated`: Whether the device is simulated.
346
+
*`template` : The device template definition for the device.
347
+
*`organizations` : List of organization IDs that the device is a part of. Currently, you can only associate a device with a single organization.
348
+
349
+
The response to this request looks like the following example:
### Add and associate a device group to an organization
368
+
369
+
Use the following request to create and associate a new device group with an organization.
370
+
371
+
```http
372
+
PUT https://{your app subdomain}.azureiotcentral.com/api/deviceGroups/{deviceGroupId}?api-version=2022-05-31
373
+
```
374
+
375
+
When you create a device group, you define a `filter` that selects the devices to add to the group. A `filter` identifies a device template and any properties to match. The following example creates device group that contains all devices associated with the "dtmi:modelDefinition:dtdlv2" template where the `provisioned` property is true.
376
+
377
+
```json
378
+
{
379
+
"displayName": "Device group 1",
380
+
"description": "Custom device group.",
381
+
"filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
382
+
"organizations": [
383
+
"seattle"
384
+
]
385
+
}
386
+
```
387
+
388
+
The request body has some required fields:
389
+
390
+
*`@displayName`: Display name of the device group.
391
+
*`@filter`: Query defining which devices should be in this group.
392
+
*`description`: Short summary of device group.
393
+
*`organizations` : List of organization IDs that the device is a part of. Currently, you can only associate a device with a single organization.
394
+
395
+
The response to this request looks like the following example:
396
+
397
+
```json
398
+
{
399
+
"id": "group1",
400
+
"displayName": "Device group 1",
401
+
"description": "Custom device group.",
402
+
"filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
403
+
"organizations": [
404
+
"seattle"
405
+
]
406
+
}
407
+
```
408
+
190
409
## Next steps
191
410
192
411
Now that you've learned how to manage organizations with the REST API, a suggested next step is to [How to use the IoT Central REST API to manage data exports.](howto-manage-data-export-with-rest-api.md)
0 commit comments