BMC Helix User Management API Guide

Auth method: JWT Bearer Token (obtained via username/password login endpoint)

Setup steps

1. POST credentials to /api/jwt/login with 'username' and 'password' form fields to receive a JWT token.
2. Include the JWT token in subsequent requests as 'Authorization: AR-JWT ' header.
3. Token expiry is configurable by the Helix administrator (default is typically 3600 seconds).
4. To invalidate a token, POST to /api/jwt/logout with the Authorization header.
5. For server-to-server integrations, create a dedicated service account in BMC Helix with appropriate permissions and use its credentials to obtain tokens programmatically.

Authenticate / Get JWT Token

• Method: POST
• URL: https://<tenant>.onbmc.com/api/jwt/login
• Watch out for: The response body is the raw JWT string (not JSON-wrapped). Store and pass it as 'Authorization: AR-JWT '.

Request example

POST /api/jwt/login
Content-Type: application/x-www-form-urlencoded

username=admin&password=secret

Response example

HTTP 200 OK

"AR-JWT eyJhbGciOiJIUzI1NiJ9..."

List Users

• Method: GET
• URL: https://<tenant>.onbmc.com/api/arsys/v1/entry/User
• Watch out for: Use the 'fields' parameter to limit returned fields; omitting it returns all fields and can be slow for large user sets.

Request example

GET /api/arsys/v1/entry/User?fields=values(Login+Name,Full+Name,Status)&limit=50&offset=0
Authorization: AR-JWT <token>

Response example

{
  "entries": [
    {"_links":{},"values":{"Login Name":"jdoe","Full Name":"John Doe","Status":"Current"}}
  ]
}

Get User by Login Name

• Method: GET
• URL: https://<tenant>.onbmc.com/api/arsys/v1/entry/User/<Login-Name>
• Watch out for: The entry ID in the URL path is the Login Name, not an internal numeric ID.

Request example

GET /api/arsys/v1/entry/User/jdoe
Authorization: AR-JWT <token>

Response example

{
  "values": {
    "Login Name": "jdoe",
    "Full Name": "John Doe",
    "Email Address": "jdoe@example.com",
    "Status": "Current"
  }
}

Create User

• Method: POST
• URL: https://<tenant>.onbmc.com/api/arsys/v1/entry/User
• Watch out for: License Type is required and must match a valid license type configured in your Helix instance. Incorrect values return a 400 error.

Request example

POST /api/arsys/v1/entry/User
Authorization: AR-JWT <token>
Content-Type: application/json

{"values":{"Login Name":"jsmith","Password":"P@ssw0rd","Full Name":"Jane Smith","License Type":"Fixed"}}

Response example

HTTP 201 Created
Location: /api/arsys/v1/entry/User/jsmith

Update User

• Method: PUT
• URL: https://<tenant>.onbmc.com/api/arsys/v1/entry/User/<Login-Name>
• Watch out for: PUT replaces only the fields provided; fields not included in the payload are not cleared (partial update behavior). BMC Helix AR REST API uses PUT for field-level updates, not full replacement.

Request example

PUT /api/arsys/v1/entry/User/jsmith
Authorization: AR-JWT <token>
Content-Type: application/json

{"values":{"Email Address":"jsmith@example.com","Phone Number":"555-1234"}}

Response example

HTTP 204 No Content

Deactivate User (Set Status to Obsolete)

• Method: PUT
• URL: https://<tenant>.onbmc.com/api/arsys/v1/entry/User/<Login-Name>
• Watch out for: There is no dedicated 'disable' endpoint. Setting Status to 'Obsolete' (value 1) prevents login. Hard deletion of users is generally discouraged in ITSM systems due to audit trail requirements.

Request example

PUT /api/arsys/v1/entry/User/jsmith
Authorization: AR-JWT <token>
Content-Type: application/json

{"values":{"Status":"Obsolete"}}

Response example

HTTP 204 No Content

Search Users with Query

• Method: GET
• URL: https://<tenant>.onbmc.com/api/arsys/v1/entry/User?q='Status'="Current"
• Watch out for: The 'q' parameter uses AR System qualification syntax (not SQL or OData). Field names must be wrapped in single quotes and values in double quotes. URL-encode the query string.

Request example

GET /api/arsys/v1/entry/User?q=%27Status%27%3D%22Current%22&limit=100&offset=0
Authorization: AR-JWT <token>

Response example

{
  "entries": [
    {"values":{"Login Name":"jdoe","Full Name":"John Doe"}},
    {"values":{"Login Name":"jsmith","Full Name":"Jane Smith"}}
  ]
}

Logout / Invalidate Token

• Method: POST
• URL: https://<tenant>.onbmc.com/api/jwt/logout
• Watch out for: Always logout service account tokens when done to avoid token accumulation. Tokens also expire based on server-side configuration.

Request example

POST /api/jwt/logout
Authorization: AR-JWT <token>

Response example

HTTP 204 No Content

• Rate limits: BMC Helix does not publicly document specific rate limit thresholds or per-plan tiers in its official REST API documentation. Rate limiting behavior is configurable at the server/tenant level by administrators.

• Rate-limit headers: No

• Retry-After header: No

• Rate-limit notes: No publicly documented rate limit headers or Retry-After behavior found in official docs. Administrators can configure throttling via BMC Helix Platform settings.

• Pagination method: offset

• Default page size: 10

• Max page size: 0

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

• Webhooks available: No

• Webhook notes: BMC Helix does not expose a native outbound webhook system for user lifecycle events in its publicly documented REST API. Event-driven integrations are typically handled via BMC Helix Integration Service or AR System filters/escalations.

• Alternative event strategy: Use BMC Helix Integration Service (formerly BMC Helix iPaaS) or AR System server-side filters/escalations to trigger external HTTP calls on record changes. Polling the User form via REST API is the standard programmatic approach.

• SCIM available: No
• SCIM version: Not documented
• Plan required: N/A
• Endpoint: Not documented

Limitations:

• BMC Helix does not natively expose a SCIM 2.0 endpoint for user provisioning as of available documentation.
• SCIM-based provisioning can be achieved via third-party identity providers (e.g., Okta, Azure AD) using custom SCIM connectors or BMC Helix Integration Service as a middleware layer.
• No official BMC documentation confirms a native /scim/v2 endpoint on the Helix Platform.

Three primary automation scenarios are supported by the API.

First, provisioning: POST to /api/arsys/v1/entry/User with Login Name, Full Name, Email Address, and License Type;

the License Type value must exactly match a string configured in the target instance - coordinate with the Helix administrator before automating.

Second, deactivation: PUT to /api/arsys/v1/entry/User/<Login-Name> with {"values":{"Status":"Obsolete"}};

there is no dedicated disable endpoint, and hard deletion is unsupported via API due to audit trail requirements.

Third, bulk audit: GET with ?q=%27Status%27%3D%22Current%22 using AR System qualification syntax (not OData or SQL), paginating with offset and limit

there is no total-count field in the response, so pagination must continue until a partial page is returned.

Provision a new employee account

1. POST to /api/jwt/login with service account credentials to obtain an AR-JWT token.
2. POST to /api/arsys/v1/entry/User with the new user's Login Name, Password, Full Name, Email Address, and License Type in the request body.
3. Capture the Location header from the 201 response to confirm the created user's Login Name.
4. Optionally, PUT to /api/arsys/v1/entry/User/ to assign Group List memberships for role-based access.
5. POST to /api/jwt/logout to invalidate the service account token.

Watch out for: License Type must exactly match a valid license type string configured in the target Helix instance. Coordinate with the Helix administrator to confirm valid values before automating provisioning.

Deactivate a departed employee

1. POST to /api/jwt/login to obtain an AR-JWT token.
2. GET /api/arsys/v1/entry/User/ to confirm the user exists and retrieve current Status.
3. PUT to /api/arsys/v1/entry/User/ with body {"values":{"Status":"Obsolete"}} to disable login.
4. POST to /api/jwt/logout.

Watch out for: Setting Status to 'Obsolete' prevents login but retains the user record and all associated ITSM history. Hard deletion is not recommended and may not be supported via API depending on instance configuration.

Bulk-list active users for audit

1. POST to /api/jwt/login to obtain an AR-JWT token.
2. GET /api/arsys/v1/entry/User?q=%27Status%27%3D%22Current%22&fields=values(Login+Name,Full+Name,Email+Address,License+Type)&limit=100&offset=0
3. Check if the number of returned entries equals the limit; if so, increment offset by 100 and repeat.
4. Continue paginating until a response returns fewer entries than the limit.
5. POST to /api/jwt/logout.

Watch out for: There is no 'total count' field in the response to know the full result set size in advance. You must paginate until a partial page is returned. For very large tenants, use narrow field selections and specific status filters to reduce response payload size.

Several non-obvious behaviors create integration risk. Field names in request and response bodies use AR System display labels with spaces (e.g., Login Name, Group List), not camelCase or snake_case. The entry ID in URL paths is the Login Name string, not a numeric or UUID identifier, which breaks assumptions common in identity graph construction.

PUT behaves as a partial update - fields omitted from the payload are not cleared - but there is no documented native PATCH support. Rate limit thresholds are not publicly documented and are configurable per tenant, meaning behavior can differ across environments with no standard Retry-After header to rely on.

Pagination is offset-based with no cursor mechanism; large tenant audits require iterating with incrementing offsets and narrow field selections to avoid slow responses.