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.

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: