MicroStrategy User Management API Guide

Auth method: Session token (Bearer) obtained via POST /auth/login; standard username/password credential exchange. OAuth 2.0 is NOT explicitly documented for user-management endpoints in official sources.

Setup steps

1. POST /api/auth/login with JSON body {username, password, loginMode} to obtain an authToken.
2. Include the authToken as HTTP header 'X-MSTR-AuthToken: ' on all subsequent requests.
3. Optionally include 'X-MSTR-ProjectID' header when project-scoped operations are needed.
4. Session expires after inactivity; call POST /api/auth/keepAlive to extend, or re-authenticate.
5. Call POST /api/auth/logout to invalidate the token when done.

Authenticate (get session token)

• Method: POST
• URL: /api/auth/login
• Watch out for: Token is returned in the response header X-MSTR-AuthToken, not the body. loginMode 1 = standard auth; 16 = SAML.

Request example

POST /api/auth/login
Content-Type: application/json
{
  "username": "admin",
  "password": "pass",
  "loginMode": 1
}

Response example

HTTP 204 No Content
X-MSTR-AuthToken: abc123tokenvalue
Set-Cookie: JSESSIONID=...

List users

• Method: GET
• URL: /api/users
• Watch out for: Use nameBegins or abbreviationBegins query params to filter. Large environments should always paginate with offset/limit.

Request example

GET /api/users?offset=0&limit=50
X-MSTR-AuthToken: abc123tokenvalue

Response example

{
  "users": [
    {"id":"GUID1","name":"John Doe","username":"jdoe","enabled":true},
    {"id":"GUID2","name":"Jane Smith","username":"jsmith","enabled":true}
  ]
}

Get user by ID

• Method: GET
• URL: /api/users/{userId}
• Watch out for: userId must be the MSTR GUID, not the username string.

Request example

GET /api/users/ABCD1234-5678-EFGH
X-MSTR-AuthToken: abc123tokenvalue

Response example

{
  "id": "ABCD1234-5678-EFGH",
  "name": "John Doe",
  "username": "jdoe",
  "enabled": true,
  "memberships": [{"id":"GRP1","name":"Analysts"}]
}

Create user

• Method: POST
• URL: /api/users
• Watch out for: Password complexity is enforced by server security policy. Omit password field only if SSO/trusted auth is the sole login method.

Request example

POST /api/users
X-MSTR-AuthToken: abc123tokenvalue
Content-Type: application/json
{
  "username": "newuser",
  "name": "New User",
  "password": "Str0ngP@ss",
  "enabled": true
}

Response example

HTTP 201 Created
{
  "id": "NEWGUID-1234",
  "name": "New User",
  "username": "newuser",
  "enabled": true
}

Update user

• Method: PATCH
• URL: /api/users/{userId}
• Watch out for: Uses JSON Patch (RFC 6902) operationList format, not a plain JSON merge. Incorrect op format returns 400.

Request example

PATCH /api/users/NEWGUID-1234
X-MSTR-AuthToken: abc123tokenvalue
Content-Type: application/json
{
  "operationList": [
    {"op":"replace","path":"/enabled","value":false}
  ]
}

Response example

HTTP 200 OK
{
  "id": "NEWGUID-1234",
  "name": "New User",
  "username": "newuser",
  "enabled": false
}

Delete user

• Method: DELETE
• URL: /api/users/{userId}
• Watch out for: Deletion is permanent and cannot be undone. Disabling (enabled=false) is recommended over deletion for audit trail preservation.

Request example

DELETE /api/users/NEWGUID-1234
X-MSTR-AuthToken: abc123tokenvalue

Response example

HTTP 204 No Content

List user groups

• Method: GET
• URL: /api/usergroups
• Watch out for: Group membership changes are made via PATCH on the user object's memberships field, not directly on the group endpoint.

Request example

GET /api/usergroups?offset=0&limit=50
X-MSTR-AuthToken: abc123tokenvalue

Response example

{
  "userGroups": [
    {"id":"GRP1","name":"Analysts"},
    {"id":"GRP2","name":"Admins"}
  ]
}

Get current user session info

• Method: GET
• URL: /api/sessions
• Watch out for: Returns info for the authenticated session only; not a list of all active sessions.

Request example

GET /api/sessions
X-MSTR-AuthToken: abc123tokenvalue

Response example

{
  "id": "SESSIONGUID",
  "userId": "USERGUID",
  "username": "admin",
  "userFullName": "Administrator"
}

• Rate limits: MicroStrategy does not publish explicit public rate limit tiers for its REST API. Limits are governed by server-side configuration (Intelligence Server and Web Server settings) and deployment sizing. No documented per-minute or per-hour numeric caps found in official sources.

• Rate-limit headers: No

• Retry-After header: No

• Rate-limit notes: Administrators can configure max concurrent sessions and connection pool sizes in MicroStrategy System Administration. Cloud/SaaS deployments may impose undocumented throttling. Contact MicroStrategy support for specific limits.

• Pagination method: offset

• Default page size: 50

• Max page size: 200

• Pagination pointer: offset and limit query parameters (e.g., ?offset=0&limit=50)

• Webhooks available: No

• Webhook notes: MicroStrategy REST API does not expose a native webhook/event subscription system for user lifecycle events (create, update, delete) as documented in official sources.

• Alternative event strategy: Use polling against GET /api/users with timestamp or change-detection logic, or leverage SCIM provisioning events from the IdP (Okta, Entra ID) which push changes to MicroStrategy via SCIM 2.0.

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Enterprise (Strategy One, September 2025 release or later)

• Endpoint: https:///MicroStrategyLibrary/scim/v2

• Supported operations: GET /Users, GET /Users/{id}, POST /Users, PUT /Users/{id}, PATCH /Users/{id}, DELETE /Users/{id}, GET /Groups, GET /Groups/{id}, POST /Groups, PATCH /Groups/{id}, DELETE /Groups/{id}, GET /ServiceProviderConfig, GET /Schemas

Limitations:

• Requires Enterprise plan; not available on lower tiers.
• SSO (SAML via Okta or Entra ID) must be configured as a prerequisite.
• Added in Strategy One September 2025 release; not available in older MicroStrategy versions.
• Supported IdPs documented: Okta and Microsoft Entra ID. Google Workspace and OneLogin not documented.
• SCIM token-based auth required; session tokens from /auth/login are not used for SCIM endpoints.

Three automation scenarios cover the primary lifecycle operations.

First, provisioning a new analyst: authenticate, resolve the target group GUID via GET /api/usergroups, create the user with POST /api/users, then assign group membership via PATCH /api/users/{id} using JSON Patch RFC 6902 format - a plain JSON merge body will return 400.

Second, deactivating a departed employee: resolve the username to a GUID via GET /api/users? nameBegins=, then PATCH with {op:'replace', path:'/enabled', value:false}; prefer this over DELETE to preserve owned objects and audit history.

Third, automated provisioning via SCIM 2. 0: requires Strategy One (September 2025+) on Enterprise plan with SAML SSO already operational; the SCIM bearer token is separate from REST session tokens and must be generated in the MicroStrategy admin console before configuring the IdP.

Supported IdPs are Okta and Microsoft Entra ID; Google Workspace and OneLogin are not documented.

Provision a new analyst user and add to a group

1. POST /api/auth/login with admin credentials to obtain X-MSTR-AuthToken.
2. GET /api/usergroups?nameBegins=Analysts to retrieve the target group GUID.
3. POST /api/users with {username, name, password, enabled:true} to create the user; capture returned user GUID.
4. PATCH /api/users/{newUserGuid} with operationList op=add path=/memberships value=[{id: groupGuid}] to assign group membership.
5. POST /api/auth/logout to invalidate the admin session token.

Watch out for: Group membership is managed via PATCH on the user object, not via a separate group-membership endpoint. Use JSON Patch format or the call will return 400.

Disable (deactivate) a departed employee

1. POST /api/auth/login to obtain admin token.
2. GET /api/users?nameBegins= to resolve the user's GUID.
3. PATCH /api/users/{userId} with operationList [{op:'replace', path:'/enabled', value:false}] to disable the account.
4. Optionally PATCH to remove group memberships to revoke data access.
5. POST /api/auth/logout.

Watch out for: Disabling is preferred over DELETE to preserve audit history and owned objects. A disabled user cannot log in but their objects remain intact.

Automate user provisioning via SCIM 2.0 with Okta

1. Ensure Strategy One (Sept 2025+) Enterprise plan is active and SAML SSO with Okta is configured.
2. In MicroStrategy admin console, enable SCIM provisioning and generate a SCIM bearer token.
3. In Okta Admin, add MicroStrategy as a SCIM 2.0 application; set SCIM base URL to https:///MicroStrategyLibrary/scim/v2 and paste the bearer token.
4. Configure Okta attribute mappings for userName, displayName, emails, and groups.
5. Assign users/groups in Okta; Okta will POST /scim/v2/Users to create accounts and PATCH to update or deactivate.
6. Verify provisioning logs in both Okta and MicroStrategy admin console.

Watch out for: SCIM provisioning requires SSO to already be working; attempting SCIM setup before SSO is configured will result in authentication failures on provisioned accounts. SCIM token is separate from REST API session tokens.

Several API behaviors are non-obvious and will break integrations silently. User IDs are internal MicroStrategy GUIDs - you cannot operate on a user by username string alone; every workflow must include a lookup step to resolve username to GUID first.

Pagination defaults to 50 records with a maximum of 200 per page using offset/limit parameters; large environments that skip pagination will receive incomplete user lists without an error. Session tokens expire after a server-configured idle timeout (commonly 30 minutes); integrations must implement keepAlive polling or re-authentication logic.

The base URL path /MicroStrategyLibrary/api is the default web context root and may differ in non-standard deployments. SCIM endpoints return 404 on any deployment not running Strategy One September 2025 or later - version and plan validation should be part of any pre-flight check.

No native webhooks exist for user lifecycle events; event-driven workflows must rely on IdP-side SCIM push or polling against GET /api/users with change-detection logic.