Manage server-level privileges

tip

You can try out this workflow at REST API Playground.

Learn more about MicroStrategy REST API Playground here.

A high-level workflow sample for managing server-level privileges is shown below. The sequence of REST API requests in the following procedure allows an administrative user to get server-level privilege information for a specific user or user group, grant new server-level privileges to the user, and revoke granted server-level privileges.

info

The DssXmlPrivilegesUseUserManager privilege is required to retrieve user privileges.

A detailed explanation of each step is provided below:

Log in

Endpoint: POST /api/auth/login

This endpoint allows the caller to authenticate with the MicroStrategy REST server. You provide the information used to create the session in the body of the request. In this example, you use standard authentication, so you need to provide the username, password, and loginMode. The loginMode specifies the authentication mode to use. If you omit an optional field, the REST server uses the default value. If the call is successful, the resulting HTTP response returns a status code of 204 and a response header containing X-MSTR-AuthToken. This authorization token is used by all subsequent requests.

In the following example, standard authentication uses a username of administrator and a blank password.

Sample request

Request Header:

'Content-Type: application/json'
'Accept: application/json'

Request Body:

To use standard authentication, set loginMode to 1.

{
  "loginMode": 1,
  "username": "administrator",
  "password": ""
}

Curl:

curl -X POST "https://demo.microstrategy.com/MicroStrategyLibrary/api/auth/login" -H "accept: application/json"-
H "Content-Type: application/json" -d "{\\"username\\":\\"administrator\\",\\"password\\":\\"\\",\\"loginMode\\":1}"

Sample response

Response Header:

The x-mstr-authtoken authorization token is returned in the response header. Other endpoints use this token to authenticate users.

{
  "pragma": "no-cache",
  "x-mstr-authtoken": "pdcmrontjrlf494tl1eu6nt7hg",
  "cache-control": "no-cache, no-store, max-age=0, must-revalidate",
  "date: Tue, 14 May 2019 20:29:21 GMT expires: 0",
  "expires": "0",
  "content-type": null
}

Response Body: Empty

Response Code: 204 (Success: No Content)

Get server-level privilege information for a specific user or group

Endpoints:

GET /api/users/{id}/privileges
GET /api/usergroups/{id}/privileges

These endpoints allow administrative users to retrieve user privilege information. First, you obtain the authorization token needed to execute the request using POST /api/auth/login. Then, you pass the authorization token in the request header. You provide the information in the parameters of the request.

The example below demonstrates how to get server-level privilege information.

Sample request

Request Parameters:

X-MSTR-AuthToken

The authorization token generated by POST /api/auth/login.
Id

The ID of the user.
privilegeLevel

Use server to retrieve server-level privileges, project to retrieve project-level privileges, and leave this parameter empty to retrieve all privileges.
projectID

Filter privileges by project.

Request Header:

'Accept: application/json'
‘X-MSTR-AuthToken: djoofk6kq8htka6emv15246959’

Curl:

curl -X GET "http://localhost:8282/consume-dev/api/users/6C9DFE134D0F8764893B469525E38EB0/privileges?privilege.level=server" -H "accept: application/json" -H "X-MSTR-AuthToken: djoofk6kq8htka6emv15246959"

Sample response

Response Header:

access-control-allow-headers: Content-Type
access-control-allow-methods: GET, POST, DELETE, PUT, PATCH, HEAD, OPTIONS
cache-control: no-store
content-encoding: gzip
content-length: 1307
content-security-policy: frame-ancestors 'self'
content-type: application/json
date: Thu, 27 Feb 2020 00:28:01 GMT
x-content-type-options: nosniff
x-xss-protection: 1; mode=block

Response Body:

The API returns a list of server-level privileges the user was granted directly or indirectly. The source of each privilege is provided. The source is either directly granted and/or inherited from a parent user group. In this example, the user has a privilege ID of 2, which is the Create configuration objects privilege. There are two sources, none are directly granted, and they are inherited from the User Administrators and System Administrators parent user groups.

{
  "privileges": [
    {
      "privilege": {
        "id": "2",
        "name": "Create configuration objects",
        "description": "This is the privilege required to create a configuration-level object.",
        "level": "server"
      },
      "sources": [
        {
          "direct": false,
          "group": {
            "name": "User Administrators",
            "id": "17CD5CDB43085A8A52533B86A05DCB3A"
          }
        },
        {
          "direct": false,
          "group": {
            "name": "System Administrators",
            "id": "5F3FAFE111D2D8CC6000CC8E67019608"
          }
        }
      ]
    },
    {
      "privilege": {
        "id": "53",
        "name": "Monitor Database Connections",
        "description": "Allow the user to monitor database connections and view connection details.",
        "level": "server"
      },
      "sources": [
        {
          "direct": true
        }
      ]
    }
  ]
}

Response Code: 200 (Success)

Grant or revoke directly assigned privileges

The following endpoints, used to patch users and user groups, are also used to grant or revoke directly assigned privileges with new operations:

PATCH /api/users/{id}
PATCH /api/userGroups/{id}

Privileges are directly granted if you use the endpoints listed above to grant them. These direct privileges can only be removed using the same endpoints.

Multiple operations, passed with the request body, can be performed in one patch request. You define the functionality in these operations. Each operation contains the following:

Operator: add for grant, remove for revoke
Path: \privileges to specify the entry to update. You cannot mix two types of operations together.
Value: A list of integers with enum values to represent privilege types. See EnumDSSXML.PrivilegeType. for more information.

The request body can contain other operations other than privileges, which are applied in the same request.

The workflow for both granting and removing privileges are as follows:

Obtain the authorization token needed to execute the request using POST /api/auth/login and pass the authorization token in the request header.
Identify the user or user group to update by specifying the ID in the path of the request. You can obtain the ID using GET /api/users orGET /api/usergroups.
Provide the information to update the privileges in the body parameter of the request. This means the body of the request contains the operations to be performed on a user by either granting or revoking privileges

Sample request

Request Parameters:

X-MSTR-AuthToken

The authorization token generated by `POST /api/auth/login.``
Id

The ID of the user or user group to update.
body

Contains the information used to perform the update, as described above.

Request Header:

'Accept: application/json'
"X-MSTR-AuthToken": "pdcmrontjrlf494tl1eu6nt7hg"

Request Parameters:

"X-MSTR-AuthToken": " pdcmrontjrlf494tl1eu6nt7hg",
"id": "F80E38174DA4A8AF4C82D18F34A2D5E8"

Request Body:

{
  "operationList": [
    {
      "op": "add",
      "path": "/privileges",
      "value": [2, 54]
    },
    {
      "op": "remove",
      "path": "/privileges",
      "value": [53]
    }
  ]
}

Curl:

curl -X PATCH curl -X PATCH "http://localhost:8282/consume-dev/api/users/6C9DFE134D0F8764893B469525E38EB0" -H "accept: application/json" -H "X-MSTR-AuthToken: cmjt8jfn2ucl260lqtrhh4gips" -H "Content-Type: application/json" -d "{ \\"operationList\\": [ { \\"op\\": \\"add\\", \\"path\\": \\"/privileges\\", \\"value\\": [2, 54] }, { \\"op\\": \\"remove\\", \\"path\\": \\"/privileges\\", \\"value\\": [53] }, ]}"

Sample response

Response Header:

access-control-allow-headers: Content-Type
access-control-allow-methods: GET, POST, DELETE, PUT, PATCH, HEAD, OPTIONS
cache-control: no-store
content-encoding: gzip
content-length: 790
content-security-policy: frame-ancestors 'self'
content-type: application/json
date: Thu, 27 Feb 2020 16:38:44 GMT
x-content-type-options: nosniff
x-xss-protection: 1; mode=block

Response Body:

The REST server returns a JSON object that contains the updated information for the user or user group.

{
  "name": "Demo User",
  "id": "6C9DFE134D0F8764893B469525E38EB0",
  "type": 34,
  "abbreviation": "demo",
  "subtype": 8704,
  "dateCreated": "2005-01-18T18:18:26.000+0000",
  "dateModified": "2020-02-27T16:38:44.000+0000",
  "version": "17BAA8CD4491C9640410E083579C09C0",
  "acg": 255,
  "owner": {
    "name": "Administrator",
    "id": "54F3D26011D2896560009A8E67019608"
  },
  "acl": [
    {
      "deny": false,
      "type": 1,
      "rights": 255,
      "trusteeId": "5F3FAFE111D2D8CC6000CC8E67019608",
      "trusteeName": "System Administrators",
      "trusteeType": 34,
      "trusteeSubtype": 8705,
      "inheritable": false
    }
  ],
  "extType": 0,
  "ancestors": [
    {
      "name": "CASTOR_SERVER_CONFIGURATION",
      "id": "5F90C74FB2944D70930B9BDDA6D2FBF1",
      "level": 2
    },
    {
      "name": "Users",
      "id": "73F7482611D3596C60001B8F67019608",
      "level": 1
    }
  ],
  "username": "demo",
  "fullName": "Demo User",
  "enabled": true,
  "passwordModifiable": false,
  "requireNewPassword": false,
  "standardAuth": true,
  "memberships": [
    {
      "id": "C82C6B1011D2894CC0009D9F29718E4F",
      "name": "Everyone",
      "source": {
        "type": ["MSTR"]
      }
    },
    {
      "id": "C2E4DA4A411B972B063FE8A583989959",
      "name": "MicroStrategy Web Professional",
      "source": {
        "type": ["MSTR"]
      }
    },
    {
      "id": "0AA72D6042B938FF3FBED3AAC39349F5",
      "name": "Mobile Users",
      "source": {
        "type": ["MSTR"]
      }
    },
    {
      "id": "5F3FAFE111D2D8CC6000CC8E67019608",
      "name": "System Administrators",
      "source": {
        "type": ["MSTR"]
      }
    },
    {
      "id": "17CD5CDB43085A8A52533B86A05DCB3A",
      "name": "User Administrators",
      "source": {
        "type": ["MSTR"]
      }
    }
  ],
  "initials": "DU"
}

Response Code: 200 (Success: OK)

The response is irrelevant to the privilege update. This is expected behavior. Remember that you are updating a user or user group. The response body is with the JSON of the user object. You can retrieve privilege information again to verify the updates.

Log out

Endpoint: POST /api/auth/logout

This endpoint allows the caller to log out the authenticated user from the MicroStrategy REST server. In this example, you close the active user session by providing the X-MSTR-AuthToken authorization token, which is generated by POST /api/auth/login. If the call is successful, the resulting HTTP response returns an HTTP status code of 204.

Sample request

Request Header:

'Accept: application/json'
'X-MSTR-AuthToken: pdcmrontjrlf494tl1eu6nt7hg'

Request Body: No content

Curl:

curl -X POST -i -c ~/cookie-jar.txt --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'X-MSTR-AuthToken: pdcmrontjrlf494tl1eu6nt7hg'
'https://demo.microstrategy.com/MicroStrategyLibrary/api/auth/logout'

Sample response

Response Code: 204 (Success: OK)

Log in​

Sample request​

Sample response​

Get server-level privilege information for a specific user or group​

Sample request​

Sample response​

Grant or revoke directly assigned privileges​

Sample request​

Sample response​

Log out​

Sample request​

Sample response​

Log in

Sample request

Sample response

Get server-level privilege information for a specific user or group

Sample request

Sample response

Grant or revoke directly assigned privileges

Sample request

Sample response

Log out

Sample request

Sample response