Version 2020

Manage Server-Level Privileges

A high-level sample workflow 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.

  1. Log in

    The endpoint, POST/auth/log, is called by a user to authenticate an environment.

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

    The following endpoint retrieves privilege information for a user:

    GET /users/{id}/privileges

    The following endpoint retrieves privilege information for a user group:

    GET /usergroups/{id}/privileges

  3. Grant or revoke directly assigned privileges

    Use the following endpoints to patch users and user groups that are used to grant or revoke directly assigned privileges with new operations:

    • PATCH /users/{id}
    • PATCH /userGroups/{id}
  4. Log out

    A user calls the GET /auth/logout endpoint to end the current session.

A detailed explanation of each step is provided below:

Log In

Endpoint: POST/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 /users/{id}/privileges
  • GET /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 /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 /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 /users/{id}
  • PATCH /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:

  1. Obtain the authorization token needed to execute the request using POST /auth/login and pass the authorization token in the request header.
  2. 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 /users or GET /usergroups.
  3. 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 /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 /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 /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)