Share via

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

maxLength: 48
pattern: ^[a-zA-Z0-9-_]*$

Unique ID for the user.
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:

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

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

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

Object

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

Object

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

Object

The response error definition.

Name Type Description
error

ErrorDetails

Error details for current request.

ErrorDetails

Object

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 (date-time-rfc1123)

The time that error request failed.

RoleAssignment

Object

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

Object

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.