BMC Remedy (Helix ITSM) User Management API Guide

Auth method: Token-based (JWT). A login endpoint exchanges credentials for a JWT token passed as an Authorization header on subsequent requests.

Setup steps

1. POST credentials (username + password) to /api/jwt/login to receive a JWT token.
2. Include the token in subsequent requests as: Authorization: AR-JWT
3. Token expires after a configurable server-side timeout (default 3600 seconds).
4. Logout via POST /api/jwt/logout to invalidate the token.
5. Ensure the AR System user account has REST API access permissions granted by an administrator.

Authenticate / Get JWT Token

• Method: POST
• URL: https://<server>:<port>/api/jwt/login
• Watch out for: Token is returned as plain text in the response body, not JSON. Store and pass 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://<server>:<port>/api/arsys/v1/entry/User
• Watch out for: Returns all User form fields by default; use 'fields' query param to restrict returned fields and reduce payload size.

Request example

GET /api/arsys/v1/entry/User?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 (qualified query)

• Method: GET
• URL: https://<server>:<port>/api/arsys/v1/entry/User?q=%27Login+Name%27%3D%22jdoe%22
• Watch out for: Query strings must be URL-encoded. AR System qualification syntax differs from SQL; use single quotes around field names.

Request example

GET /api/arsys/v1/entry/User?q='Login+Name'="jdoe"
Authorization: AR-JWT <token>

Response example

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

Create User

• Method: POST
• URL: https://<server>:<port>/api/arsys/v1/entry/User
• Watch out for: The new record's Request ID is returned only in the Location header, not in the response body.

Request example

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

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

Response example

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

Update User

• Method: PUT
• URL: https://<server>:<port>/api/arsys/v1/entry/User/<Request-ID>
• Watch out for: PUT replaces only the fields provided; omitted fields retain their current values. Use the numeric Request ID in the path, not the Login Name.

Request example

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

{"values":{"Status":"Disabled","Email Address":"jsmith@example.com"}}

Response example

HTTP 204 No Content

Delete User

• Method: DELETE
• URL: https://<server>:<port>/api/arsys/v1/entry/User/<Request-ID>
• Watch out for: Deletion is permanent and cannot be undone via API. Consider setting Status=Disabled instead of deleting to preserve audit history.

Request example

DELETE /api/arsys/v1/entry/User/000000000000001
Authorization: AR-JWT <token>

Response example

HTTP 204 No Content

Logout / Invalidate Token

• Method: POST
• URL: https://<server>:<port>/api/jwt/logout
• Watch out for: Always logout to free server-side session resources; tokens do not auto-expire immediately on the server unless the timeout elapses.

Request example

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

Response example

HTTP 204 No Content

Get User Groups

• Method: GET
• URL: https://<server>:<port>/api/arsys/v1/entry/Group
• Watch out for: Group membership is managed on the User record's 'Group List' field, not via a separate membership endpoint.

Request example

GET /api/arsys/v1/entry/Group?limit=100
Authorization: AR-JWT <token>

Response example

{
  "entries": [
    {"values":{"Group ID":"1","Group Name":"Administrators","Group Type":"Regular"}}
  ]
}

• Rate limits: BMC AR System does not publish explicit per-plan API rate limits in official documentation. Throttling is controlled server-side via AR System configuration parameters (e.g., Max Entries, thread pool settings). No documented rate-limit response headers.

• Rate-limit headers: No

• Retry-After header: No

• Rate-limit notes: Administrators configure concurrency and entry limits in the AR System server settings. No publicly documented numeric rate limits per tier.

• Pagination method: offset

• Default page size: 0

• Max page size: 0

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

• Webhooks available: No

• Webhook notes: BMC AR System does not provide native outbound webhooks in the traditional sense. Event-driven notifications are handled via AR System Filters and Escalations configured server-side.

• Alternative event strategy: Use AR System Filters with 'Run Process' or 'Notify' actions to trigger external HTTP calls on record changes. Third-party integration platforms (e.g., BMC Helix iPaaS) can also poll the REST API for changes.

• SCIM available: No
• SCIM version: Not documented
• Plan required: Enterprise
• Endpoint: Not documented

Limitations:

• BMC Remedy / Helix ITSM does not expose a native SCIM 2.0 endpoint.
• User provisioning via SCIM requires a third-party identity provider connector or middleware (e.g., Okta SCIM connector configured against the AR System REST API).
• No official BMC documentation confirms a built-in SCIM endpoint as of the latest reviewed release (AR System 23.08).

Three automation scenarios cover the majority of lifecycle operations.

For provisioning, POST to /api/arsys/v1/entry/User with Login Name, Full Name, Password, License Type, and Status=Current;

the new record's Request ID is returned only in the Location response header, not the body - capture it immediately.

For deprovisioning, prefer a PUT to set Status=Disabled over a DELETE;

deletion is permanent and removes audit history.

For bulk audit or identity graph reconciliation, paginate GET /api/arsys/v1/entry/User using offset and limit query parameters with a fields filter to restrict payload size

the API does not return a total record count, so iterate until the entries array is empty.

Functional role assignments (e.g., Incident Master, Change Coordinator) are stored on the People record, not the User record, and require separate API calls to /api/arsys/v1/entry/CTM:People to be included in any complete identity graph.

Provision a new ITSM user account

1. POST to /api/jwt/login with admin credentials to obtain a JWT token.
2. POST to /api/arsys/v1/entry/User with required fields: Login Name, Full Name, Password, License Type, Status=Current.
3. Extract the new user's Request ID from the Location response header.
4. Optionally PUT to /api/arsys/v1/entry/User/ to set additional fields (email, department, group membership).
5. POST to /api/jwt/logout to invalidate the admin token.

Watch out for: License Type must be set correctly at creation; assigning an unavailable license type will return a server-side error. Verify available license counts before bulk provisioning.

Disable a departed employee's account

1. POST to /api/jwt/login to obtain a JWT token.
2. GET /api/arsys/v1/entry/User?q='Login+Name'="" to retrieve the user's Request ID.
3. PUT to /api/arsys/v1/entry/User/ with body {"values":{"Status":"Disabled"}}.
4. Confirm the update by GETting the user record and verifying Status=Disabled.
5. POST to /api/jwt/logout.

Watch out for: Setting Status=Disabled prevents login but preserves the user record and audit history. Deletion via DELETE is irreversible.

Bulk-list users for audit / reconciliation

1. POST to /api/jwt/login to obtain a JWT token.
2. GET /api/arsys/v1/entry/User?fields=values(Login+Name,Full+Name,Status,License+Type,Email+Address)&limit=100&offset=0.
3. Iterate by incrementing offset by 100 until the returned entries array is empty.
4. Aggregate results for audit comparison against HR or IdP directory.
5. POST to /api/jwt/logout.

Watch out for: Use the 'fields' query parameter to limit returned data; omitting it returns all form fields and significantly increases response payload size and latency.

Several non-obvious behaviors create integration risk. AR System qualification syntax (used in the q query parameter) uses single-quoted field names and is not SQL or OData-compatible - malformed queries fail silently or return empty result sets rather than a 400 error in some server versions. BMC does not publish numeric rate limits;

throttling is governed by server-side thread pool and Max Entries configuration parameters with no rate-limit response headers and no Retry-After support, making backoff logic harder to implement reliably. There is no native SCIM 2.0 endpoint as of AR System 23.08; SCIM-based provisioning requires a third-party connector or middleware layer.

On-premise deployments may expose the API over HTTP on non-standard ports (default mid-tier: 8080) - verify TLS configuration before transmitting credentials. Finally, API calls do not bypass AR System field-level or form-level permissions;

the authenticated service account must be explicitly granted REST API access and appropriate permission groups by an administrator, or reads and writes will fail without a clear permission-denied message in all cases.