Manage server settings
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.
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.
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.
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.
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)