Users - Create

Service:

IoT Central

API Version:

2022-07-31

Create a user in the application

PUT https://{subdomain}.{baseDomain}/api/users/{userId}?api-version=2022-07-31

URI Parameters

Name	In	Required	Type	Description
baseDomain	path	True	string	The base domain for all Azure IoT Central service requests.
subdomain	path	True	string	The application subdomain.
userId	path	True	string	Unique ID for the user. Regex pattern: ^[a-zA-Z0-9-_]*$
api-version	query	True	string	The version of the API being called.

Request Body

The request body can be one of the following:

Name	Description
ADGroupUser	The active directory group user definition.
EmailUser	The email user definition.
ServicePrincipalUser	The service principal user definition.

ADGroupUser

The active directory group user definition.

Name	Required	Type	Description
objectId	True	string	The AAD object ID of the AD Group.
roles	True	RoleAssignment[]	List of role assignments that specify the permissions to access the application.
tenantId	True	string	The AAD tenant ID of the AD Group.
type	True	string: adGroup	Type of the user.

EmailUser

The email user definition.

Name	Required	Type	Description
email	True	string	Email address of the user.
roles	True	RoleAssignment[]	List of role assignments that specify the permissions to access the application.
type	True	string: email	Type of the user.

ServicePrincipalUser

The service principal user definition.

Name	Required	Type	Description
objectId	True	string	The AAD object ID of the service principal.
roles	True	RoleAssignment[]	List of role assignments that specify the permissions to access the application.
tenantId	True	string	The AAD tenant ID of the service principal.
type	True	string: servicePrincipal	Type of the user.

Responses

Name	Type	Description
200 OK	User: ADGroupUser EmailUser ServicePrincipalUser	Success
Other Status Codes	Error	An error response received from the IoT Central Service. Headers x-ms-error-code: string

Security

azure_auth

Azure Active Directory OAuth2 Flow

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

Name	Description
user_impersonation	impersonate your user account

Examples

Add or update a service principal user

Add or update an email user

Add or update a service principal user

Sample request

HTTP

PUT https://appsubdomain.azureiotcentral.com/api/users/123?api-version=2022-07-31

{
  "type": "servicePrincipal",
  "tenantId": "027fdad7-cf0f-470a-a26a-272197813322",
  "objectId": "65e13aac-1443-4c49-9d49-57b87197cfff",
  "roles": [
    {
      "role": "c7be2c6b-797e-4551-bb24-33709f6b2e20"
    },
    {
      "role": "c495eb57-eb18-489e-9802-62c474e5645c",
      "organization": "seattle"
    }
  ]
}

Sample response

Status code:

200

{
  "id": "123",
  "type": "servicePrincipal",
  "tenantId": "027fdad7-cf0f-470a-a26a-272197813322",
  "objectId": "65e13aac-1443-4c49-9d49-57b87197cfff",
  "roles": [
    {
      "role": "c7be2c6b-797e-4551-bb24-33709f6b2e20"
    },
    {
      "role": "c495eb57-eb18-489e-9802-62c474e5645c",
      "organization": "seattle"
    }
  ]
}

Add or update an email user

Sample request

HTTP

PUT https://appsubdomain.azureiotcentral.com/api/users/123?api-version=2022-07-31

{
  "type": "email",
  "roles": [
    {
      "role": "ca310b8d-2f4a-44e0-a36e-957c202cd8d4"
    },
    {
      "role": "c495eb57-eb18-489e-9802-62c474e5645c",
      "organization": "seattle"
    }
  ],
  "email": "bob@contoso.com"
}

Sample response

Status code:

200

{
  "type": "email",
  "roles": [
    {
      "role": "ca310b8d-2f4a-44e0-a36e-957c202cd8d4"
    },
    {
      "role": "c495eb57-eb18-489e-9802-62c474e5645c",
      "organization": "seattle"
    }
  ],
  "email": "bob@contoso.com"
}

Definitions

Name	Description
ADGroupUser	The active directory group user definition.
EmailUser	The email user definition.
Error	The response error definition.
ErrorDetails	The detail information of the error.
RoleAssignment	The role assignment definition.
ServicePrincipalUser	The service principal user definition.

ADGroupUser

The active directory group user definition.

Name	Type	Description
id	string	Unique ID of the user.
objectId	string	The AAD object ID of the AD Group.
roles	RoleAssignment[]	List of role assignments that specify the permissions to access the application.
tenantId	string	The AAD tenant ID of the AD Group.
type	string: adGroup	Type of the user.

EmailUser

The email user definition.

Name	Type	Description
email	string	Email address of the user.
id	string	Unique ID of the user.
roles	RoleAssignment[]	List of role assignments that specify the permissions to access the application.
type	string: email	Type of the user.

Error

The response error definition.

Name	Type	Description
error	ErrorDetails	Error details for current request.

ErrorDetails

The detail information of the error.

Name	Type	Description
code	string	Error code.
message	string	Error message details.
requestId	string	Correlation Id for current request.
time	string	The time that error request failed.

RoleAssignment

The role assignment definition.

Name	Type	Description
organization	string	ID of the organization for this role assignment.
role	string	ID of the role for this role assignment.

ServicePrincipalUser

The service principal user definition.

Name	Type	Description
id	string	Unique ID of the user.
objectId	string	The AAD object ID of the service principal.
roles	RoleAssignment[]	List of role assignments that specify the permissions to access the application.
tenantId	string	The AAD tenant ID of the service principal.
type	string: servicePrincipal	Type of the user.