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.

Roles

The following roles are available.

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
CI/CD configuration	role.workspace.ci_cd_agent.configure	(For API Access keys only.) Scope: All workspaces

Add a role to a user

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
}

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
}

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"
}
```

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.

Connect to OpenText Core Software Delivery Platform as a site admin user:

POST .../authentication/sign_in

{"user":"<site admin user name>","password":"<site admin password>"}
Get the ID of the site admin role:

GET .../admin/roles?query="logical_name EQ ^role.site.admin^"
Retrieve the site admin role ID from the response.

List the roles the user currently has:

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

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

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"
                                }]
                }
}

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"
                                }]
                }
}