Skip to main content

Manage server settings

Available since 2021

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 settings is shown below. The sequence of REST API requests in the following procedure allows an administrative user to manage the Intelligence Server settings.

info

The DssXmlPrivilegesConfigureGoverning and DssXmlPrivilegesConfigureServerBasic privileges are required to manage server settings.

A detailed explanation of each step is provided below.

Log in

Endpoint: POST /api/auth/login

This endpoint allows the user to authenticate with the MicroStrategy REST Server. You can provide the information used to create the session in the body of the request. In this example, you can use standard authentication, so you need to provide the username and password. If the call is successful, the resulting 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 Body:

{
"username": "administrator",
"password": "yourPassword"
}

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\\":\\"yourPassword\\"}"

Sample response

Response Header:

cache-control: no-cache, no-store, max-age=0, must-revalidate
date: Mon, 28 Oct 2019 17:38:15 GMT
expires: 0
pragma: no-cache
x-mstr-authtoken: f34qc7evsntsks0qe6hfcgt0ur

Response Code: 204 (Success: No Content)

Get the Intelligence Server setting configurations

Endpoint: GET /api/v2/iserver/settings/config

This endpoint allows the user to retrieve information on all Intelligence Server settings that are available in MicroStrategy REST API. The information includes the setting description, type, options, unit, minimum value, maximum value, and reboot rule. You must specify an authorization token in the request header, which can be obtained from POST /api/auth/login during login.

tip

This operation requires the Web User privilege.

Sample request

Request Parameter:

X-MSTR-AuthToken

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

Curl:

curl -X GET "https://demo.microstrategy.com/MicroStrategyLibrary/api/v2/iserver/settings/config" -H "accept: application/json" -H "X-MSTR-AuthToken: 562f9s80514s26mm7qhi47o96f"

Sample response

Response Body:

The following sample is part of the complete response body.

{
"maxUserConnectionPerServer": {
"description": "Maximum number of user sessions",
"type": "number",
"max_value": 1000,
"min_value": 0,
"multi_select": false,
"options": [
{
"name": "No Limit",
"value": -1
}
]
},
"maxUserConnectionIdleTime": {
"description": "Tools session idle time (sec)",
"type": "number",
"unit": "second",
"reboot_rule": {
"rule": "changed",
"precondition": "reboot_iserver",
"description": "The setting will take effect after restart Intelligence Server"
},
"max_value": 999999,
"min_value": 0,
"multi_select": false,
"options": [
{
"name": "No Limit",
"value": -1
}
]
}
}

Response Code: 200 (Success: OK)

Get the Intelligence Server setting values

Endpoint: GET /api/v2/iserver/settings

This endpoint allows you to retrieve all Intelligence Server setting values that are available in MicroStrategy REST API. You must specify an authorization token in the request header, which can be obtained from POST /api/auth/login during login.

Sample request

Request Parameter:

X-MSTR-AuthToken

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

Curl:

curl -X GET "https://demo.microstrategy.com/MicroStrategyLibrary/api/v2/iserver/settings/config" -H

Sample response

Response Body:

The following sample is part of the complete response body.

{
"maxUsedVirtualByte": {
"value": 99
},
"importSAPUser": {
"value": false
},
"maxInboxMsgLifeTime": {
"value": -1
},
"hashIterations": {
"value": 10000
},
"tokenTTL": {
"value": 1440
},
"loadBalanceMode": {
"value": false
}
}

Response Code: 200 (Success: OK)

Update a part of the Intelligence Server setting values

Endpoint: PATCH /api/v2/iserver/settings

This endpoint allows you to modify part of the project settings exposed in REST API via GET /api/v2/iserver/settings/config. You must specify an authorization token in the request header, which can be obtained from POST /api/auth/login during login.

tip

Depending on the setting you are modifying, the response body will tell you which privilege is required for the operation.

Sample request

Request Parameter:

X-MSTR-AuthToken

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

Request Body:

{
"maxUsedVirtualByte": {
"value": 98
},
"importSAPUser": {
"value": true
}
}

Curl:

curl -X PATCH "https://demo.cloud.microstrategy.com/MicroStrategyLibrary/api/v2/iserver/settings" -H "accept: application/json" -H "X-MSTR-AuthToken: 562f9s80514s26mm7qhi47o96f" -H "Content-Type: application/json" -d "{\\"maxUsedVirtualByte\\":{\\"value\\":98},\\"importSAPUser\\":{\\"value\\":true}}"

Sample response

Response Body:

The following sample is part of the complete response body. A complete list of Intelligence Server setting values with the modified values should be returned.

{
"maxUsedVirtualByte": {
"value": 98
},
"importSAPUser": {
"value": true
},
"maxInboxMsgLifeTime": {
"value": -1
},
"hashIterations": {
"value": 10000
},
"tokenTTL": {
"value": 1440
}
}

Response Code: 200 (Success: OK)

Update all Intelligence Server setting values

Endpoint: PUT /api/v2/iserver/settings

This endpoint allows you to access all of the Intelligence Server setting values that are available in MicroStrategy REST API. In this endpoint, you must provide a complete list of Intelligence Server settings, which is the different from the PATCH /api/v2/iserver/settings endpoint. You can find a list of Intelligence Server settings exposed in REST API via GET /api/v2/iserver/settings/config. You must specify an authorization token in the request header, which can be obtained from POST /api/auth/login during login.

tip

This operation requires the following privileges:

  • Configure Server Basic
  • Configure Governing
  • Configure History Lists
  • Configure Security Settings
  • Configure Statistics
  • Configure Caches
  • Create and Edit Database Instances and Connections

Sample request

Request Parameter:

X-MSTR-AuthToken

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

Request Body:

The following sample is part of the complete request body. The complete request body must contain all Intelligence Server settings.

{
"maxUsedVirtualByte": {
"value": 99
},
"importSAPUser": {
"value": false
},
"maxInboxMsgLifeTime": {
"value": -1
},
"hashIterations": {
"value": 10000
},
"tokenTTL": {
"value": 1440
},
"loadBalanceMode": {
"value": false
}
}

Curl:

curl -X PUT "https://demo.microstrategy.com/MicroStrategyLibrary/api/v2/iserver/settings" -H "accept: application/json" -H "X-MSTR-AuthToken: 562f9s80514s26mm7qhi47o96f" -H "Content-Type: application/json" -d "{\\"maxUsedVirtualByte\\":{\\"value\\":99},\\"importSAPUser\\":{\\"value\\":false},\\"maxInboxMsgLifeTime\\":{\\"value\\":-1},\\"hashIterations\\":{\\"value\\":10000},\\"tokenTTL\\":{\\"value\\":1440},\\"loadBalanceMode\\":{\\"value\\":false},...}"

Sample response

Response Body:

The following sample is part of the complete response body. A complete list of Intelligence Server setting values with the modified values should be returned.

{
"maxUsedVirtualByte": {
"value": 99
},
"importSAPUser": {
"value": false
},
"maxInboxMsgLifeTime": {
"value": -1
},
"hashIterations": {
"value": 10000
},
"tokenTTL": {
"value": 1440
},
"loadBalanceMode": {
"value": false
}
}

Response Code: 200 (Success: OK)

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 response returns a status code of 204.

Sample request

Curl:

curl -X POST "https:// demo.microstrategy.com/MicroStrategyLibrary/api/auth/logout" -H "accept: application/json" -H "X-MSTR-AuthToken: c8afkjurl1r9qk2k7puj2hs9cu"

Sample response

Response Code: 204 (Accepted)