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.

The root context is the base context for all webservice requests. Specific requests must construct a path consisting of this base context plus the specific functionality.

context	URL

context	URL
root context with https	[root_context] = https://[host]:[port]/[application_name]/ws
process interface	[root_context]/processes/
task interface	[root_context]/tasks/
tenant selection

Depending on the configuration of your server and authorization mechanism, the protocol can be HTTP or HTTPS. For more information, see the previous section.

Make sure you specify the right port for your application server.

To select the tenant id, append the tenant id to the URL, that is, the primary key of the tenant in the database:

[URL]?tenantId=xxx

Example: Start process with tenant selection

http://myServer:8080/idm-operator/ws/processes/MyProcess/start?tenantId=1234

By default, no secrets are resolved when querying for example the data map of a certain process step.

If the user which calls the REST API has the EXECUTION permission api.resolveSecrets, which can be defined in the designer, then secrets are resolved. The field is the same as the one which would contain the UUID of the secretFieldStore, for example Person_PasswordRef.

To run a command on a specific task, you will need a taskId.

To find the taskId, look up the value of the id attribute of the specific process in the BPMN 2.0 process definition, in the file process.xml.

Or, if you rather want to get the information from the database, look into the table ACT_RU_TASK in the column Task_Def_Key_. Don´t use ID_.

Available commands

Supported field types

There are three possible values for the type attribute of a field:

Type	Default	Description

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.
PEM is not supported.

DATE

For date values, given in the format %Y-%M-%DT%h:%m:%s%z

Example:

2001-10-25T00:00:00+02:00