Preventing cross site request forgery

Edit online

To prevent cross site request forgery attacks, the Business Automation Workflow 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 Business Automation Workflow REST API operations must include a valid token in the HTTP header BPMCSRFToken.

Any attempt to call an Business Automation Workflow 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.

Cloud environments: Client applications must use the following URL: 
https://subscription_hostname/cloud_offering/environment/bpm/system/login
where
  • subscription_hostname can be one of the following values: bpm.ibmcloud.com or automationcloud.ibm.com
  • cloud_offering can take one of the following values:
    • baw for Business Automation Workflow on Cloud
    • dba for cloud subscriptions with multiple IBM® Digital Business Automation on Cloud offerings, including Business Automation Workflow on Cloud
    • bpm for IBM BPM on Cloud
  • environment has the value dev for the development environment, test for the test environment, or run for the production (runtime) environment. A token for one environment is not valid for another environment.