role
Important
This is the Azure Sphere (Legacy) documentation. Azure Sphere (Legacy) is retiring on 27 September 2027, and users must migrate to Azure Sphere (Integrated) by this time. Use the Version selector located above the TOC to view the Azure Sphere (Integrated) documentation.
Manages user roles in tenants for role-based access control (RBAC).
| Operation | description |
|---|---|
| add | Adds a role for a user. |
| delete | Removes a user role. |
| list | Displays a list of users and their roles. |
| show | Returns roles assigned to a particular user account. |
| show-types | Displays a list of roles supported for this tenant. |
add
Adds a role to a user.
- An Administrator has full access to all devices and operations within the tenant, including the permission to add or delete other users. The Administrator role is assigned by default to the user who creates the tenant.
- A Contributor can add devices and create and change deployments. Software and hardware developers who create applications, manage connected devices, and update deployments, but are not responsible for managing tenant access, should have the Contributor role.
- A Reader has access to information about the tenant, including the claimed devices, deployments, and, when available, any error reporting data from the devices. This role is appropriate for maintenance and operations personnel who are responsible for tracking connected device performance at end-user installations.
Note
This command will automatically register the user's Microsoft account with Azure Sphere, if they are not yet registered. Previously, the register-user command was used to register a new user with Azure Sphere; this is now automatically done when adding a user to a new role within an existing tenant, and the register-user command is now deprecated.
Required parameters
| Parameter | Type | Description |
|---|---|---|
| -u, --user | String | Specifies the name of the user (email address). |
| -r, --role | String | Specifies the role to assign to the selected user. Possible roles are: Administrator, Contributor, and Reader. |
Optional parameters
| Parameter | Type | Description |
|---|---|---|
| -t, --tenant | GUID or name | Specifies the tenant to perform this operation in. Overrides the default selected tenant. You can specify either the tenant ID or tenant name. |
Global parameters
The following global parameters are available for the Azure Sphere CLI:
| Parameter | Description |
|---|---|
| --debug | Increases logging verbosity to show all debug logs. If you find a bug, provide output generated with the --debug flag on when submitting a bug report. |
| -h, --help | Prints CLI reference information about commands and their arguments and lists available subgroups and commands. |
| --only-show-errors | Shows only errors, suppressing warnings. |
| -o, --output | Changes the output format. The available output formats are json, jsonc (colorized JSON), tsv (Tab-Separated Values), table (human-readable ASCII tables), and yaml. By default the CLI outputs table. To learn more about the available output formats, see Output format for Azure Sphere CLI commands. |
| --query | Uses the JMESPath query language to filter the output returned from Azure Sphere Security Services. See JMESPath tutorial and Query Azure CLI command output for more information and examples. |
| --verbose | Prints information about resources created in Azure Sphere during an operation and other useful information. Use --debug for full debug logs. |
Note
If you are using Azure Sphere classic CLI, see Global parameters for more information on available options.
Example
azsphere role add --user john@contoso.com --role Administrator
delete
Removes a role from a user in the current or selected Azure Sphere tenant.
Required parameters
| Parameter | Type | Description |
|---|---|---|
| -u, --user | String | Specifies the user's ID or email to identify the user from whom the role is being deleted. |
| -r, --role | Enum | Specifies the role to be deleted. Possible roles are: Administrator, Contributor, and Reader. |
Optional parameters
| Parameter | Type | Description |
|---|---|---|
| -t, --tenant | GUID or name | Specifies the tenant to perform this operation in. Overrides the default selected tenant. You can specify either the tenant ID or tenant name. |
Note
The Administrator role of the current user can be deleted only by another administrator.
Global parameters
The following global parameters are available for the Azure Sphere CLI:
| Parameter | Description |
|---|---|
| --debug | Increases logging verbosity to show all debug logs. If you find a bug, provide output generated with the --debug flag on when submitting a bug report. |
| -h, --help | Prints CLI reference information about commands and their arguments and lists available subgroups and commands. |
| --only-show-errors | Shows only errors, suppressing warnings. |
| -o, --output | Changes the output format. The available output formats are json, jsonc (colorized JSON), tsv (Tab-Separated Values), table (human-readable ASCII tables), and yaml. By default the CLI outputs table. To learn more about the available output formats, see Output format for Azure Sphere CLI commands. |
| --query | Uses the JMESPath query language to filter the output returned from Azure Sphere Security Services. See JMESPath tutorial and Query Azure CLI command output for more information and examples. |
| --verbose | Prints information about resources created in Azure Sphere during an operation and other useful information. Use --debug for full debug logs. |
Note
If you are using Azure Sphere classic CLI, see Global parameters for more information on available options.
Example
azsphere role delete --user bob@contoso.com --role contributor --tenant 143adbc9-1bf0-4be2-84a2-084a331d81cb
list
Displays a list of user roles in the current or selected tenant.
The list will truncate after the first 500 entries.
Optional parameters
| Parameter | Type | Description |
|---|---|---|
| -t, --tenant | GUID or name | Specifies the tenant to perform this operation in. Overrides the default selected tenant. You can specify either the tenant ID or tenant name. |
Global parameters
The following global parameters are available for the Azure Sphere CLI:
| Parameter | Description |
|---|---|
| --debug | Increases logging verbosity to show all debug logs. If you find a bug, provide output generated with the --debug flag on when submitting a bug report. |
| -h, --help | Prints CLI reference information about commands and their arguments and lists available subgroups and commands. |
| --only-show-errors | Shows only errors, suppressing warnings. |
| -o, --output | Changes the output format. The available output formats are json, jsonc (colorized JSON), tsv (Tab-Separated Values), table (human-readable ASCII tables), and yaml. By default the CLI outputs table. To learn more about the available output formats, see Output format for Azure Sphere CLI commands. |
| --query | Uses the JMESPath query language to filter the output returned from Azure Sphere Security Services. See JMESPath tutorial and Query Azure CLI command output for more information and examples. |
| --verbose | Prints information about resources created in Azure Sphere during an operation and other useful information. Use --debug for full debug logs. |
Note
If you are using Azure Sphere classic CLI, see Global parameters for more information on available options.
Example
azsphere role list --tenant 143adbc9-1bf0-4be2-84a2-084a331d81cb
--------------------- -------------
Name Roles
===================================
bob@contoso.com Administrator
Contributor
--------------------- -------------
show
Displays role information for a selected user.
Required parameters
| Parameter | Type | Description |
|---|---|---|
| -u, --user | String | User name to display (email address). |
Optional parameters
| Parameter | Type | Description |
|---|---|---|
| -t, --tenant | GUID or name | Specifies the tenant to perform this operation in. Overrides the default selected tenant. You can specify either the tenant ID or tenant name. |
Global parameters
The following global parameters are available for the Azure Sphere CLI:
| Parameter | Description |
|---|---|
| --debug | Increases logging verbosity to show all debug logs. If you find a bug, provide output generated with the --debug flag on when submitting a bug report. |
| -h, --help | Prints CLI reference information about commands and their arguments and lists available subgroups and commands. |
| --only-show-errors | Shows only errors, suppressing warnings. |
| -o, --output | Changes the output format. The available output formats are json, jsonc (colorized JSON), tsv (Tab-Separated Values), table (human-readable ASCII tables), and yaml. By default the CLI outputs table. To learn more about the available output formats, see Output format for Azure Sphere CLI commands. |
| --query | Uses the JMESPath query language to filter the output returned from Azure Sphere Security Services. See JMESPath tutorial and Query Azure CLI command output for more information and examples. |
| --verbose | Prints information about resources created in Azure Sphere during an operation and other useful information. Use --debug for full debug logs. |
Note
If you are using Azure Sphere classic CLI, see Global parameters for more information on available options.
Example
azsphere role show --user john@contoso.com --tenant 143adbc9-1bf0-4be2-84a2-084a331d81cb
-------------
Roles
=============
Administrator
Contributor
-------------
show-types
Displays roles that can be assigned in this tenant.
Global parameters
The following global parameters are available for the Azure Sphere CLI:
| Parameter | Description |
|---|---|
| --debug | Increases logging verbosity to show all debug logs. If you find a bug, provide output generated with the --debug flag on when submitting a bug report. |
| -h, --help | Prints CLI reference information about commands and their arguments and lists available subgroups and commands. |
| --only-show-errors | Shows only errors, suppressing warnings. |
| -o, --output | Changes the output format. The available output formats are json, jsonc (colorized JSON), tsv (Tab-Separated Values), table (human-readable ASCII tables), and yaml. By default the CLI outputs table. To learn more about the available output formats, see Output format for Azure Sphere CLI commands. |
| --query | Uses the JMESPath query language to filter the output returned from Azure Sphere Security Services. See JMESPath tutorial and Query Azure CLI command output for more information and examples. |
| --verbose | Prints information about resources created in Azure Sphere during an operation and other useful information. Use --debug for full debug logs. |
Note
If you are using Azure Sphere classic CLI, see Global parameters for more information on available options.
Example
azsphere role show-types
-------------
Result
=============
Administrator
-------------
Contributor
-------------
Reader
-------------