This documentation supports the 20.08 version of BMC Helix Platform.  To view an earlier version, select 20.02 from the Product version menu.

Login information

All REST API calls must be authenticated. Instead of passing the full credentials on every REST API call, REST uses a token. A new token is generated for each user request. The token is valid for a configurable amount of time and acts like a temporary password. The expiry time of the token depends on the idle timeout and absolute timeout.

Login API example

The following code is a sample REST call to login a user:

POST <SERVER-URL>/api/rx/authentication/loginrequest
Host: localhost
Accept: application/json
X-Requested-By: XMLHttpRequest
Content-Type: application/json;charset=UTF-8
{
"userName": "user",
"password": "userpassword",
"locale": "en-us"
}

The "locale": "en-us" name value pair in the above code is optional. This command returns a cookie. In subsequent REST calls, this cookie is used. 

Extending session time

If a user requests to extend the session time before the idle timeout expiry, the session remains active till absolute timeout expiry. 

The following code is a sample REST call to keep a session active:

POST http://localhost:8008/api/rx/application/command
Host: localhost
Content-Type: application/json
AR-JWT-Refresh-From: Tue, 15 Nov 2016 08:12:31 GMT
default-bundle-scope: task-manager
Content-Length: 78
{
 "resourceType" :"com.bmc.arsys.rx.application.user.command.KeepAliveCommand"
}
  • AR-JWT-Refresh-From is the HTTP header which indicates the starting time for calculating idle timeout of a user session.
  • For the requests that do not need token refresh, you must include the Suppress-Token-Refresh HTTP headers in the REST call. The value of Suppress-Token-Refresh is 1*<any US ASCII character except CTLs or separators>.

The following is a sample decoded JSON Web Token:

{
 "sub": "GudJDqg4Ww8JLIjqKEU0Ui/N3SR0hN7mu0hvNfran1hOi9P52UA92CrLZXAUC/VE7ROXFL6qUPIo9jj08HyZFWS9Z4KtXMQAwyJL6zWhJdJ0orDdvunWDQ==",
 "nbf": 1467238964,
 "_password": "OArJGmlNs6w8V29vZmWHUur5fxaiNCBV3mVuxmg650JMnS9e3RSTqmvUItnWAV5y/c54NDaaJD+8//RC+oMV4YnG+65Tqc0OerGRWtoZTQWK+U+exU4BoA==",
 "_impersonatedUser": null,
 "iss": "clm-aus-013734.clm-mgmt.clm.bmc.com",
 "_authString": "tph8/mleHvEN5hBqFchHiOhKJFsr6yTuzKNoWrF/C0RVsXx66TKIVvB3TN4spAie41ICkwB1dFx+FaFjDQbRFbN5t8LkGn07D3D24S9J4IdML+wmV+Xorg==",
 "_cacheId": 27,
 "exp": 1467242684,
 "iat": 1467239084,
 "jti": "IDGAA5V0GFFS2AOJKAXIOIOKSQ4SHK",
 "_absoluteExpirationTime": 1467325484
}

  • exp (Expiration Time)—JSON numeric value representing the number of seconds from 1970-01-01T00:00:00Z UTC till specified UTC date/time, ignoring leap seconds. It represents the user session expiry time, when the user is idle. It is calculated based on the Session-Idle-Timeout configuration.
  • _absoluteExpirationTime—JSON numeric value representing the number of seconds from 1970-01-01T00:00:00Z UTC till specified UTC date/time, ignoring leap seconds. It represents the maximum time to which the current user session can be extended. It is calculated based on the Session-Absolute-Timeout configuration.

Related topics

Creating-a-DataPageQuery-REST-interface

Creating-a-command-REST-interface

Creating-a-custom-REST-resource