User Web Services
Overview
Universal Controller supports the following RESTful-based web services for User operations, which are listed alphabetically on this page.
- Create a User
- Delete a User
- List Users
- Modify a User
- Read a User
- List User Preferences
- Read a User Preference
- Update a User Preference
- Create Personal Access Token
- List Personal Access Tokens
- Revoke Personal Access Token
Formatting specifications for each web service, including details about parameter requirements, are provided.
Note
If you want to change only the User's password, rather than modifying the whole User record, you can use the Password API.
Permissions
The following table identifies the web service operations that a user can perform
Operation | User without any role | User with ops_service_role | User with ops_user_admin or ops_admin role |
---|---|---|---|
Read | Read its own record (details). Read its own Role, Permissions, and Member of Groups (group membership), | Read any user record. | Create/update/read/delete any fields or any related data. |
Update | Update a subset of fields of its own record. Cannot update any related data. | Update a subset of fields of its own record. Cannot update any related data. | |
Create | No permission to create a user. | No permission to create a user. | |
Delete | No permission to delete a user. | No permission to delete a user. |
Create a User
Description | |
---|---|
URI | http://host_name/uc/resources/user |
HTTP Method | |
Description | Creates a new User. |
Example URI | http://localhost:8080/uc/resources/user |
Consumes Content-Type | application/xml, application/json |
Produces Content-Type | n/a |
Example | See Create, Modify, and Read a User: XML and JSON Examples: XML and JSON Examples, below. |
User Properties | See User Properties, below. |
User Permission Properties | See User Permission Properties, below. |
User Role Properties | See User Role Properties, below. |
Example Response |
|
Create, Modify, and Read a User: XML and JSON Examples
The excludeRelated and retainSysIds properties are specified as attributes in the <user> element of XML web services.
XML | JSON |
---|---|
Delete a User
Description | |
---|---|
URI | http://host_name/uc/resources/user |
HTTP Method | DELETE |
Description | Deletes a User. |
URI Parameters | See Delete a User URI Parameters, below. |
Example URI | |
Example Response |
|
Delete a User: URI Parameters
Parameter | Description | Specifications | Required | Mutually Exclusive With |
---|---|---|---|---|
| ID used within the Controller to identify this user. | String; URI parameter. | Y (unless |
|
| Name used within the Controller to identify this user. | String; URI parameter. | Y (unless |
|
List Users
Description | |
---|---|
URI | http://host_name/uc/resources/user/list |
HTTP Method | GET |
Description | Retrieves information on all Users. |
Example URI | http://localhost:8080/uc/resources/user/list http://localhost:9090/uc/resources/user/list?showTokens=true |
Authentication | HTTP Basic |
Produces Content-Type | application/xml, application/json |
Example | |
User Properties | See User Properties. |
User Permission Properties | |
User Role Properties | See User Role Properties. |
List Users: URI Parameters
Name | Description | Specifications | Required |
---|---|---|---|
| Show personal access tokens. | Boolean
| N |
List Users: XML and JSON Examples
XML | JSON |
---|---|
Modify a User
Description | |
---|---|
URI | http://host_name/uc/resources/user |
HTTP Method | PUT |
Description | Modifies the User specified by the sysId in the request. |
Example URI | http://localhost:8080/uc/resources/user |
Consumes Content-Type | application/xml, application/json |
Produces Content-Type | n/a |
Example | |
User Properties | See User Properties. |
User Permission Properties | |
User Role Properties | See User Role Properties. |
Example Response |
|
Read a User
Description | |
---|---|
URI | http://host_name/uc/resources/user |
HTTP Method | GET |
Description | Retrieves information on a specific User. |
URI Parameters | See Read a User: URI Parameters, below. |
Example URI | |
Consumes Content-Type | n/a |
Produces Content-Type | application/xml, application/json |
User Properties | See User Properties. |
User Permission Properties | |
User Role Properties | See User Role Properties. |
Example Response |
|
Read a User: URI Parameters
Name | Description | Specifications | Required | Mutually Exclusive With |
---|---|---|---|---|
| Unique ID for this User. | Y |
| |
| Name used within the Controller to identify this User. | Maximum 40 alphanumerics. | Y |
|
| Show personal access tokens. | Boolean
| N |
List User Preferences
URI | http://host_name:port/uc/resources/user/preference/list |
HTTP Method | GET |
Description | Retrieves information on all user preferences for a particular user. |
Example URI | http://localhost:8080/uc/resources/user/preference/list?username=ops.admin |
Authentication | HTTP Basic |
Produces Content-Type | Application/XML, Application/JSON |
Consumes Content-Type | N/A |
Example Responses |
|
List User Preferences: URI Parameters
Property | Description | Required | Mutual Exclusive With |
---|---|---|---|
| Unique ID for this User. | N |
|
| Name used within the Controller to identify this User. | N |
|
List User Preferences: XML and JSON Examples
XML | JSON |
---|---|
Read a User Preference
URI | http://host_name:port/uc/resources/user/preference |
HTTP Method | GET |
Description | Retrieves information on a specific user preference for a particular user. |
Example URI | http://localhost:8080/uc/resources/user/preference?preferencename=uc.activity.monitor_automatically&username=ops.admin |
Authentication | HTTP Basic |
Produces Content-Type | Application/XML, Application/JSON |
Consumes Content-Type | N/A |
Example Responses |
|
Read a User Preference: URI Parameters
Property | Description | Specifications | Required | Mutual Exclusive With |
---|---|---|---|---|
| User preference name. | Y | ||
| Unique ID for this User. | N |
| |
| Name used within the Controller to identify this User. | N |
|
Read a User Preference: XML and JSON Examples
XML | JSON |
---|---|
Update a User Preference
URI | http://host_name:port/uc/resources/user/preference |
HTTP Method | PUT |
Description | Modify a user preference for a particular user. |
Example URI | http://localhost:8080/uc/resources/user/preference?preferencename=uc.activity.monitor_automatically&value=No&username=ops.admin |
Authentication | HTTP Basic |
Example Responses |
|
Update a User Preference: URI Parameters
Property | Description | Specifications | Required | Mutual Exclusive With |
---|---|---|---|---|
| User preference name. | Y | ||
| User preference value. | See User Preference Properties. | Y | |
| Unique ID for this User. | N |
| |
| Name used within the Controller to identify this User. | N |
|
Properties
User Properties
Property | UI Field Name | Description | Specifications | Required |
---|---|---|---|---|
| Active | Specification for whether or not the user is active. An active user can log in to the Controller. An inactive user cannot log in to the Controller, and the user will not appear in user lists. | Boolean. Valid Values: true/false. Default is false. | N |
| Web Browser Access | Specification for whether or not the user can log in to the user interface. | Valid Values:
Default is – System Default – (0). | N |
| Business Phone | Business phone number of this user. | N | |
| Command Line Access | Specification for whether or not the user can log in to the Universal Controller Command Line Interface (CLI). | Valid values:
Default is – System Default – (0). | N |
| Department | Business department of this user. | N | |
| Email address of this user. | N | ||
| n/a | For the Modify User web service; specification for whether or not to exclude related records (User Permissions, User Roles) from the update, even if they are provided in the request. Note In XML, | Valid values: true/false (default is false). | N |
| First Name | First Name of this user. | N | |
| Allowed Impersonation Users | Specifies the users that can be impersonated by this user using the X-Impersonate-User HTTP header on Web Service requests. User impersonation requires the ops_user_impersonate role. Users with the ops_admin role can impersonate any user and do not need to specify Allowed Impersonation Users. Format: <impersonate> <allowed>jane.doe</allowed> <allowed>john.doe</allowed> </impersonate> JSON "impersonate": [ "jane.doe", "john.doe" ] | N | |
| Last Name | Last Name of this user. | N | |
| Locked out | Specification for whether or not the user is locked out of the Controller. | Boolean. Valid Values: true/false. Default is false. | N |
|