This documentation is for a version that is out of support.

You may want to view the same page for the latest version, or for any of the versions available in the drop-down menu in the top-right corner.

REST API authentication

To call the REST API, you must first log on with a user registered in the Engine database.

Login to Bonita

To log in, use the following request:

Request URL

http://host:port/bonita/loginservice

Request Method

POST

Content-Type

application/x-www-form-urlencoded

Form Data

username: a username
password: a password
redirect: true or false. false indicates that the service should not redirect to Bonita Portal (after a successful login) or to the login page (after a login failure).
redirectURL: the URL of the page to be displayed after login
tenant: the tenant to log in to (optional for Performance edition, not supported for Community, Teamwork and Efficiency editions)

The response to this call generates cookies. The JSESSIONID must be transfered with each subsequent calls. If the REST API is used in an application running in a web browser, this is handled automatically by the web browser. For usage of the X-Bonita-API-Token see below.

The security against CSRF attacks is enabled by default for all fresh installations.

This security relies on X-Bonita-API-Token information. The X-Bonita-API-Token value can be found in the cookie named: X-Bonita-API-Token. All the subsequence REST API calls using DELETE, POST, or PUT HTTP methods must contain the HTTP header below:

X-Bonita-API-Token: example-dummy-not-be-used-value

Example using Curl

Login

$ curl -v -c saved_cookies.txt -X POST --url 'http://localhost:8080/bonita/loginservice' \
--header 'Content-Type: application/x-www-form-urlencoded' -o /dev/null \
-d 'username=walter.bates&password=bpm&redirect=false&redirectURL='

The above curl command saved the cookies on the disk, in the saved_cookies.txt file. The cookies file must be reused with the REST API calls (HTTP requests) in order to provide session information. The value of X-Bonita-API-Token cookie must be passed also in the header of the subsequent REST API calls, when any of the POST, PUT or DELETE HTTP method is used.

The content of the cookies file is below:

$ cat saved_cookies.txt

localhost	FALSE	/bonita/	FALSE	0	bonita.tenant	1
#HttpOnly_localhost	FALSE	/bonita/	FALSE	0	JSESSIONID	9F9665280B367259AC421378B69C3244
localhost	FALSE	/	FALSE	0	X-Bonita-API-Token	2f86dcab-9b54-45e6-8eb1-f82c2a2f8e25

Call an API when authenticated

Let’s list processes from the API by providing authentication information.

$ curl -b saved_cookies.txt -X GET --url 'http://localhost:8080/bonita/API/bpm/process?c=100&p=0'

Let’s create a new 'Create supplier' process instance (from Studio example "Procurement") by providing the X-Bonita-API-Token header, the required body and the 'Create supplier' id (modify 5975558489041216684 by the Process ID of your environment, given in output from the previous curl command above).

 $ curl -b saved_cookies.txt -X POST -H "Content-Type: application/json" --header 'X-Bonita-API-Token: 2f86dcab-9b54-45e6-8eb1-f82c2a2f8e25' --data '{"supplierInput":{"name":"My supplier","description":"This is the best supplier"}}' --url "http://localhost:8080/bonita/API/bpm/process/5975558489041216684/instantiation"

Logout from Bonita

When processing is complete, you must log out.

To log out, use the following request:

Request URL

http://host:port/bonita/logoutservice

Request Method

GET

Query parameter

redirect: true or false (default set to true)

Setting the redirect parameter to false indicates that the service should not redirect to the login page after logging out.

Troubleshooting

HTTP/1.1 401 Unauthorized

If the HTTP response’s status is 401 Unauthorized:

  • make sure that the cookies have been transfered with the call

  • make sure that the cookies transfered are the ones generated during the last sucessfull login call

  • if one of the PUT, DELETE or POST method is used, make sure that the X-Bonita-API-Token header is included

  • if the X-Bonita-API-Token header is included, make sure that the value is the same as the one of the cookie generated during the last login

  • Maybe a logout was issued or the session has expired; try to log in again, and re run the request with the new cookies and the new value for the X-Bonita-API-Token header.