Skip to content

Commit 8a145b5

Browse files
ShannonLeavittShannonLeavitt
authored
Merge pull request #191146 from v-krishnag/restorgs
rest api organizations
2 parents 837800a + fe81f96 commit 8a145b5

File tree

3 files changed

+196
-1
lines changed

3 files changed

+196
-1
lines changed

‎articles/iot-central/TOC.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -192,6 +192,8 @@
192192
href: core/howto-query-with-rest-api.md
193193
- name: Manage users and roles
194194
href: core/howto-manage-users-roles-with-rest-api.md
195+
- name: Manage organizations
196+
href: core/howto-manage-organizations-with-rest-api.md
195197
- name: Data export
196198
href: core/howto-manage-data-export-with-rest-api.md
197199
- name: Manage device templates

‎articles/iot-central/core/howto-manage-organizations-with-rest-api.md

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
---
2+
title: Use the REST API to manage organizations in Azure IoT Central
3+
description: How to use the IoT Central REST API to manage organizations in an application
4+
author: v-krishnag
5+
ms.author: v-krishnag
6+
ms.date: 03/08/2022
7+
ms.topic: how-to
8+
ms.service: iot-central
9+
services: iot-central
10+
11+
---
12+
13+
# How to use the IoT Central REST API to manage organizations
14+
15+
The IoT Central REST API lets you develop client applications that integrate with IoT Central applications. You can use the REST API to manage organizations in your IoT Central application.
16+
17+
> [!TIP]
18+
> The [organizations feature](howto-create-organizations.md) is currently available in [preview API](/rest/api/iotcentral/1.1-previewdataplane/users).
19+
20+
Every IoT Central REST API call requires an authorization header. To learn more, see [How to authenticate and authorize IoT Central REST API calls](howto-authorize-rest-api.md).
21+
22+
For the reference documentation for the IoT Central REST API, see [Azure IoT Central REST API reference](/rest/api/iotcentral/).
23+
24+
To learn more about organizations in IoT Central Application, see [Manage IoT Central organizations](howto-create-organizations.md).
25+
26+
## Organizations REST API
27+
28+
The IoT Central REST API lets you:
29+
30+
* Add an organization to your application
31+
* Get an organization by ID
32+
* Update an organization in your application
33+
* Get a list of the organizations in the application
34+
* Delete an organization in your application
35+
36+
### Create organizations
37+
38+
The REST API lets you create organizations in your IoT Central application. Use the following request to create an organization in your application:
39+
40+
```http
41+
PUT https://{subdomain}.{baseDomain}/api/organizations/{organizationId}?api-version=1.1-preview
42+
```
43+
44+
* organizationId - Unique ID of the organization
45+
46+
The following example shows a request body that adds an organization to a IoT Central application.
47+
48+
```json
49+
{
50+
"displayName": "Seattle",
51+
}
52+
```
53+
54+
The request body has some required fields:
55+
56+
* `@displayName`: Display name of the organization.
57+
58+
The request body has some optional fields:
59+
60+
* `@parent`: ID of the parent of the organization.
61+
62+
If you don't specify a parent, then the organization gets the default top-level organization as its parent.
63+
64+
The response to this request looks like the following example:
65+
66+
```json
67+
{
68+
"id": "seattle",
69+
"displayName": "Seattle"
70+
}
71+
```
72+
73+
You can create an organization with hierarchy, for example you can create a sales organization with a parent organization.
74+
75+
The following example shows a request body that adds an organization to a IoT Central application.
76+
77+
```json
78+
{
79+
"displayName": "Sales",
80+
"parent":"seattle"
81+
}
82+
```
83+
84+
The response to this request looks like the following example:
85+
86+
```json
87+
{
88+
"id": "sales",
89+
"displayName": "Sales",
90+
"parent":"Seattle"
91+
}
92+
```
93+
94+
95+
96+
### Get an organization
97+
98+
Use the following request to retrieve details of an individual organization from your application:
99+
100+
```http
101+
GET https://{subdomain}.{baseDomain}/api/organizations/{organizationId}?api-version=1.1-preview
102+
```
103+
104+
The response to this request looks like the following example:
105+
106+
```json
107+
{
108+
"id": "seattle",
109+
"displayName": "Seattle",
110+
"parent": "washington"
111+
}
112+
```
113+
114+
### Update an organization
115+
116+
Use the following request to update details of an organization in your application:
117+
118+
```http
119+
PATCH https://{subdomain}.{baseDomain}/api/organizations/{organizationId}?api-version=1.1-preview
120+
```
121+
122+
The following example shows a request body that updates an organization.
123+
124+
```json
125+
{
126+
"id": "seattle",
127+
"displayName": "Seattle Sales",
128+
"parent": "washington"
129+
}
130+
```
131+
132+
The response to this request looks like the following example:
133+
134+
```json
135+
{
136+
"id": "seattle",
137+
"displayName": "Seattle Sales",
138+
"parent": "washington"
139+
}
140+
```
141+
142+
### List organizations
143+
144+
Use the following request to retrieve a list of organizations from your application:
145+
146+
```http
147+
GET https://{your app subdomain}.azureiotcentral.com/api/organizations?api-version=1.1-preview
148+
```
149+
150+
The response to this request looks like the following example.
151+
152+
```json
153+
{
154+
"value": [
155+
{
156+
"id": "washington",
157+
"displayName": "Washington"
158+
},
159+
{
160+
"id": "redmond",
161+
"displayName": "Redmond"
162+
},
163+
{
164+
"id": "bellevue",
165+
"displayName": "Bellevue"
166+
},
167+
{
168+
"id": "spokane",
169+
"displayName": "Spokane",
170+
"parent": "washington"
171+
},
172+
{
173+
"id": "seattle",
174+
"displayName": "Seattle",
175+
"parent": "washington"
176+
}
177+
]
178+
}
179+
```
180+
181+
The organizations Washington, Redmond, and Bellevue will automatically have the application's default top-level organization as their parent.
182+
183+
### Delete an organization
184+
185+
Use the following request to delete an organization:
186+
187+
```http
188+
DELETE https://{your app subdomain}.azureiotcentral.com/api/organizations/{organizationId}?api-version=1.1-preview
189+
```
190+
191+
## Next steps
192+
193+
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)

‎articles/iot-central/core/howto-manage-users-roles-with-rest-api.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -229,4 +229,4 @@ DELETE https://{your app subdomain}.azureiotcentral.com/api/users/user-001?api-v
229229

230230
## Next steps
231231

232-
Now that you've learned how to manage users and roles 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)
232+
Now that you've learned how to manage users and roles with the REST API, a suggested next step is to [How to use the IoT Central REST API to manage organizations.](howto-manage-organizations-with-rest-api.md)

0 commit comments

Comments
 (0)