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.


Related topics

Creating-a-DataPageQuery-REST-interface

Creating-a-command-REST-interface

Creating-a-custom-REST-resource

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.


 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*