Preventing cross site request forgery

To prevent cross site request forgery attacks, the IBM® BPM REST API operations require that the HTTP header BPMCSRFToken is set with every request.

The client application must obtain the necessary token by calling the POST /bpm/system/login REST API with a JSON body that is similar to the following example.

{
  "refresh-groups": false,
  "requested-lifetime": 7200
}

Where setting the value of the refresh-groups property to false avoids the overheads that are associated with updating the group membership for the calling user, and requested-lifetime is the number of seconds that the token will be valid for. If requested-lifetime is not specified in the request, the default of 7200 seconds is used, which is the maximum permitted value.

The token is returned as a string in the csrf_token property of the response object. Every call to IBM BPM REST API operations must include a valid token in the HTTP header BPMCSRFToken.

Any attempt to call an IBM BPM REST API with an expired token fails with HTTP response code 403 and error_number CWTBG0651E in the response, which indicates that the token could not be verified and that the token must be renewed. To retrieve a new token, the client application must call the /bpm/system/login API again. The client application can then use the new token to resubmit the failed request.

Remember: For IBM BPM on Cloud, the client application must use the following URL https://hostname.bpm.ibmcloud.com/bpm/environment/system/login, where environment has the value dev for the development environment, test for the test environment, or run for the runtime environment. A token for one IBM BPM on Cloud environment is not valid for another environment.