Share this page

# PUT: Update a user's role

You can use the REST API to update users' roles.

Caution: Assigning a role to a user using the REST API overrides the existing set of roles for that user. Even if you want to add only one new role to a user, the update should include previously existing roles. Otherwise non-included roles are unassigned.

In this topic:

## ALM Octane roles

The following roles are available in ALM Octane.

For details about each role, see Roles and permissions.

Note: Roles can be customized. Contact your site admin or space admin if you need different permissions.

Name | Logical name | Notes
--- | --- | ---
Space admin | role.shared.space.admin | Allow shared space management and configuration (including user management). Scope: Shared space
Workspace admin | role.workspace.admin | Allow workspace management and configuration, including getting a list of users. Roles can be customized. Roles and their permissions might be different for your organization Scope: Workspace
Leader | role.workspace.leader | Allow management of team members and workload. Scope: Teams in workspace
Team member | role.workspace.team.member | Allow working with, and editing, items that affect the member's work as part of a team. Scope: Teams in workspace
Tester | role.workspace.tester | Allow working with, and editing, items that are related to testing. Scope: Teams in workspace
DevOps admin | role.workspace.devops.admin | Allow management of CI servers and pipelines in a workspace context. Scope: Workspace
Viewer | role.workspace.viewer | View items. Scope: Teams in workspace
Site admin | role.site.admin | Allow site admin access to ALM Octane. Scope: Site
Maintenance protocol | role.site.maintenance.protocol | Allow ALM Octane to access micro services (OPB/synchronization) on the site level. Scope: Site
Micro Service site admin | role.site.micro.service.site.admin | Allow micro services to get site users and roles from ALM Octane. Scope: Site
CI/CD configuration | role.workspace.ci_cd_agent.configure | (For API Access keys only.) Scope: All workspaces

Back to top

## Add a role to a user

1. Find the ID of the desired role according to desired workspace and role’s logical name.

   Roles might have the same logical names across different workspaces, but their IDs will be different.

   Example

   This is an example of getting the role ID.

   - Get the role of the space admin. In this case, do not specify a workspace ID. In this case, the role ID is 1007.

     Request:

     `GET .../api/shared_spaces/<sharedSpaceId>/workspace_roles?query="role EQ {logical_name EQ ^role.shared.space.admin^}"`

     Response:

         {
           "total_count": 1,
           "data": [
             {
               "type": "workspace_role",
               "creation_time": "2016-10-29T19:05:29Z",
               "workspace": null,
               "role": {
                 "type": "role",
                 "id": "1007"
               },
               "version_stamp": 1,
               "id": "1007",
               "last_modified": "2016-10-29T19:05:29Z"
             }
           ],
           "exceeds_total_count": false
         }

   - Get the role of the workspace admin in workspace 1002. In this case, the role ID is 1003.

     Request:

     `GET .../api/shared_spaces/<space_id>/workspace_roles?query="workspace EQ {id EQ ^1002^}; role EQ {logical_name EQ ^role.workspace.admin^}"`

     Response:

         {
           "total_count": 1,
           "data": [
             {
               "type": "workspace_role",
               "creation_time": "2016-10-29T19:05:29Z",
               "workspace": {
                 "type": "workspace",
                 "id": "1002"
               },
               "role": {
                 "type": "role",
                 "id": "1003"
               },
               "version_stamp": 1,
               "id": "1011",
               "last_modified": "2016-10-29T19:05:29Z"
             }
           ],
           "exceeds_total_count": false
         }

2. Find the user you want to update, such as by email, and get the existing roles for that user. We want to update the roles for Dan Mosko, whose name is Dan@mosko. His ID is 1003. His role IDs are 1011 and 1018.

   Request:

   `GET .../api/shared_spaces/<space_id>/users?fields=id,name,workspace_roles&query="name EQ ^<userName>^"`

   Response:

       {
         "total_count": 1,
         "data": [
           {
             "type": "sharedspace_user",
             "creation_time": "2016-10-30T07:14:44Z",
             "version_stamp": 1,
             "uid": "8l5m9xkkz8mr3h8jd0ywr2jek",
             "name": "Dan@mosko",
             "id": "1003",
             "workspaces": {
               "total_count": 2,
               "data": [
                 {
                   "type": "workspace",
                   "name": "DAN_TEMP",
                   "id": "1003"
                 },
                 {
                   "type": "workspace",
                   "name": "default_workspace",
                   "id": "1002"
                 }
               ]
             },
             "last_modified": "2016-10-30T07:14:44Z",
             "workspace_roles": {
               "total_count": 2,
               "data": [
                 {
                   "type": "workspace_role",
                   "workspace": {
                     "type": "workspace",
                     "name": "DAN_TEMP",
                     "id": "1003"
                   },
                   "role": {
                     "type": "role",
                     "logical_name": "role.workspace.admin",
                     "name": "Workspace Admin",
                     "id": "1003"
                   },
                   "id": "1018"
                 },
                 {
                   "type": "workspace_role",
                   "workspace": {
                     "type": "workspace",
                     "name": "default_workspace",
                     "id": "1002"
                   },
                   "role": {
                     "type": "role",
                     "logical_name": "role.workspace.admin",
                     "name": "Workspace Admin",
                     "id": "1003"
                   },
                   "id": "1011"
                 }
               ]
             }
           }
         ],
         "exceeds_total_count": false
       }

3. Update the role for the user with a PUT request.

   Example

   Assume that:

   - The existing roles of the user ID 1003 are:

     `{"workspace_roles": {"data": [{"type": "workspace_role","id": "1018"} , {"type": "workspace_role","id": "1011"}]}}`

   - The ID of the new role you want to assign is 1004.

   The update request is:

   `PUT .../api/shared_spaces/<space_id>/users/1003`

   The request body is:

   `{"workspace_roles": {"data": [{"type": "workspace_role","id": "1018"} , {"type": "workspace_role","id": "1011"} , {"type": "workspace_role","id": "1004"} ]}}`

   The response body is:

       {
         "type": "sharedspace_user",
         "id": "1003"
       }

Back to top

## Add the site admin role to a user using the REST API (on-premises)

To work with the admin REST API, the authenticated user has to have the site admin role.

1. Connect to ALM Octane as a site admin user:

   `POST .../authentication/sign_in`

   `{"user":"<site admin user name>","password":"<site admin password>"}`

2. Get the ID of the site admin role:

   `GET .../admin/roles?query="logical_name EQ ^role.site.admin^"`

3. Retrieve the site admin role ID from the response.

4. List the roles the user currently has:

       GET .../admin/users/<user id>?fields=roles

       "roles": {
                       "total_count": 1,
                       "data": [{
                                       "type": "role",
                                       "id": "<role ID>"
                       }]
       }

5. Prepare the JSON request body for the update request (in the next step) by adding the site admin role to the existing roles:

       {
                       "roles": {
                                       "data": [{
                                                       "id": "<current user role ID>",
                                                       "type": "site_role"
                                       },
                                       {
                                                       "id": "<site admin role ID>",
                                                       "type": "site_role"
                                       }]
                       }
       }

6. Update the roles of the user who should be a site admin, adding the JSON body created in the previous step:

   `PUT .../admin/users/<user ID>`

       {
                       "roles": {
                                       "data": [{
                                                       "id": "<current user role ID>",
                                                       "type": "site_role"
                                       },
                                       {
                                                       "id": "<site admin role ID>",
                                                       "type": "site_role"
                                       }]
                       }
       }

Back to top

See also:

- Working with users

https://admhelp.microfocus.com ALM Octane 8942
Tips to improve your search results... ALM Octane Help Center ALM Octane Help 23.4-24.3 All View Local Help Center View Online Help Center Version: