Identity Manager Process REST API
This article includes updates for Smart ID 23.04.
This article describes the Identity Manager Process REST API which can be used to control processes in Smart ID Identity Manager.
The API provides a simple RESTful interface for starting and proceeding processes and for exchanging data with it. The Identity Manager Process REST API is part of the Identity Manager main application and will be available automatically after starting the server that hosts the application.
Use the Identity Manager Process REST API
See the following topics for more information on how to use the Identity Manager Process REST API:
The REST API is secured by default. Therefore it is not possible for intruders to access data and functionality of the REST interface. The default configuration uses our internal authentication profile to authenticate the user and to perform the authorization.
By default, the HTTP Basic Authentication is used. The client calling our service is responsible to fill the Authorization Header of the HTTP request.
Never use the HTTP Basic Authentication without securing the communication channel using SSL, so make sure you access the server using HTTPS.
To configure the authentication process and the security settings, see the Spring Security filter settings in the security-beans.xml.
Available commands
Description
Use the Execute task endpoint of the REST API to complete the user task (open task) and control the flow of the process.
Executing a process via the public REST interface behaves as follows when the process encounters a user task:
The process stops and waits for further input
The API user must provide the form data as payload of an http request to the exec endpoint
The process continues its execution regardless of any button that is associated to the form/user task
In order to influence the execution path of the process (for example at gateways), you can also set the values of the flow variables in the payload
Examples
Example: Simulate a click on the Next button
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<data>
<field name="Person_FirstName" type="STRING">Bernhard</field>
<field name="Person_LastName" type="STRING">Adam</field>
<field name="action" type="STRING">true</field>
</data>The action variable must be true.
Example: Simulate a click on the Next button (set as default flow)
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<data>
<field name="Person_FirstName" type="STRING">Bernhard</field>
<field name="Person_LastName" type="STRING">Adam</field>
</data>The action variable is not required here.
Example: Simulate a click on the Cancel button
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<data>
<field name="Person_FirstName" type="STRING">Bernhard</field>
<field name="Person_LastName" type="STRING">Adam</field>
<field name="action" type="STRING">false</field>
</data>The action variable must be false.
The first two examples (simulating a click on the NEXT button) are alternatives.
As soon as a gateway uses a variable in its condition and there is no flow marked as default, then the variable must be set and send to the endpoint. Otherwise you get an error response.
You can not add variables to the 'Obtain task data and execute task' endpoint even though it is POST request. But you may send variables to the process when starting it.
The button function CANCEL is not supported. Executing an open user task through the REST API will always continue with the button function NEXT.
Supported field types
There are three possible values for the type attribute of a field:
Type | Default | Description |
|---|---|---|
STRING |
| For UTF-8 strings. |
BYTES |
| For binary values, given as base64. When passing CSRs, certificates and the like, always set the pure base64 value. |
DATE |
| For date values, given in the format %Y-%M-%DT%h:%m:%s%z Example:2001-10-25T00:00:00+02:00 |
