Identity Manager Public Data REST API

This article includes updates for Identity Manager 5.3.

This article describes the Identity Manager Public Data REST API which can be used to query data from Identity Manager Operator.

Settings

Since Identity Manager 5.3, the Public REST API has a configuration section in the Identity Manager Operator System Properties section.

That section provides two settings:

Open API docs enabled (yes/no)
- Make sure to keep it disabled in a production environment.
JWT max duration in minutes
- Defines how long a generated JWT remains valid. That value should be specified in minutes.
  Shorter durations enhance security by limiting the window for token misuse, while longer durations reduce the need for frequent re-authentication.

Open API

For development and testing purposes you may consult the OpenAPI documentation under http://{idm-operator-context}/ws/swagger-ui/index.html It supports the Basic Auth authorization and it is only available under certain conditions.

The Identity Manager Public Data REST API OpenAPI documentation is not displayed by default and should remain disabled in production environments to avoid exposing unnecessary information.

After Identity Manager 5.3

The System properties contains a Public REST API section where you can enable or disable the OpenAPI documentation.

The Spring profile is not needed anymore.

Before Identity Manager 5.3

It needs the openapi Spring profile to be active.

To enable the OpenAPI documentation, start the application with the following JVM (Java Virtual Machine) option:

-Dspring.profiles.active=openapi

The JVM Options can be modified by either modifying the JAVA_OPTS or CATALINA_OPTS.

Authentication API

Permissions

To request a new JW Token through the Public Data REST API, the user needs to have the permissionPublic Data ReST API: Token configured using the Roles or the User Administration in Identity Manager Admin.
Without this permission the request will be rejected with HTTP status code 403 (Forbidden).

Endpoints

`POST /auth/token`

Generates a new JWT bearer token for the authenticated user. The token is returned in the Authorization header.

You can request a token for a list of services or single service, according to your needs. See the /resources/auth/token to get the complete list.

It will help to restrict the scope of the token usage.

Parameters

Name

Type

Required

Description

tenantId

query

integer(int32)

true

The tenant ID

body

TokenRequest

true

Token request payload containing audiences and duration. The duration should be specified in minutes.

Body parameter

JSON

{
  "duration": 30,
  "services": [
    "/data/async-search",
    "/data/async-search/{name}",
    "/data/async-search/{name}/result-set/{uuid}",
    "/data/resources",
    "/data/resources/search",
    "/data/resources/search/{name}",
    "/data/search",
    "/data/search/{name}"
  ]
}

Body parameter to restrict the token to one specific service

JSON

{
  "duration": 5,
  "service": "/data/search/{name}"
}

Responses

Status	Meaning	Description	Schema
204	No Content	Token generated successfully. The token is returned in the Authorization header.	None
400	Bad Request	Invalid remote IP address or bad request.	None
401	Unauthorized	Unauthorized - The request requires authentication to access the resource.	None
403	Forbidden	Forbidden - The authenticated request requires permissions to access the resource.	None
406	Not Acceptable	Not Acceptable - There is no representation of the resource for the given accept header.	None
500	Internal Server Error	Internal server error (e.g., token header too large).	None

`GET /resources/auth/token`

Get token creation option

Returns information required for token creation, including maximum duration and available services.

Parameters

Name

Type

Required

Description

tenantId

query

integer(int32)

true

The tenant ID

Example response

JSON

{
  "duration": 30,
  "services": [
    "/data/async-search",
    "/data/async-search/{name}",
    "/data/async-search/{name}/result-set/{uuid}",
    "/data/resources",
    "/data/resources/search",
    "/data/resources/search/{name}",
    "/data/search",
    "/data/search/{name}"
  ]
}

Data API

Search configuration

Searching for data in Identity Manager is represented by a concept named SearchConfig. In general, performing a search through Identity Manager Public Data REST API will provide the same capabilities as using the GUI of Identity Manager Operator.

A SearchConfig encompasses the data source, the search filters/parameters and the resulting data output. It operates on the data structures CoreTemplate and DataPool which are basically a list of fields. The search filters allow to put constraints on fields while the data output is selected through result columns. A SearchConfig is configured via the Identity Manager Admin application.

Permissions

Every request to Identity Manager Public Data REST API requires an authentication.

For convenience it supports Basic Auth, please ensure that the Authorization HTTP header is set accordingly. Alternatively you can use Mutual TLS which requires to setup an HTTP Connector.

Since IDM 5.3 the Public Data REST API supports JWT (JSON Web Token) authentication. To request a new JWT token, see the Authentication Endpoints section.

Also the user needs a proper authorization in order to use the Public Data REST API in general. So please assign the Public Data ReST API: Search general runtime permission using the Roles or the User Administration in Identity Manager Admin.

Additionally, using a SearchConfig through the REST API requires 2 settings in Identity Manager Admin:

The purpose Public REST Api must be checked.
The user needs the 'Execute' permission.

Endpoints

This section lists the available endpoints of Identity Manager Public Data REST API. The root URL is http://{idm-operator-context}/ws

Be aware that the REST API delivers a snapshot of the data at the time of the HTTP request. The payloads are noted with JSON.

Authentication

HTTP Authentication, scheme: basic
Client Certificate
HTTP Authentication, scheme: bearer JWT

`GET /data/search/{name}`

Execute the given PRE-CONFIGURED search configuration and wait for the results.

Parameters

Name	In	Type	Required	Description
name	path	string	true	The name of the search configuration
page	query	integer(int32)	false	The page index (1..N)
pageSize	query	integer(int32)	false	The size of the page to be returned
tenantId	query	integer(int32)	true	The tenant ID

Example responses

OK - The results of the given search.

JSON

{
  "meta": {
    "name": "SearchConfigPersons",
    "date": "2025-06-05T14:49:48",
    "totalSize": 40,
    "page": 2,
    "pageSize": 10
  },
  "result": {
    "reference": {
      "type": "CORE_TEMPLATE",
      "name": "Person"
    },
    "rows": [
      {
        "FirstName": "John",
        "LastName": "Smith"
      }
    ]
  },
  "links": [
    {
      "rel": "self",
      "href": "/data/search/SearchConfigPersons?page=2&pageSize=10"
    },
    {
      "rel": "describedBy",
      "href": "/data/resources/search/SearchConfigPersons"
    },
    {
      "rel": "previous",
      "href": "/data/search/SearchConfigPersons?page=1&pageSize=10"
    },
    {
      "rel": "next",
      "href": "/data/search/SearchConfigPersons?page=3&pageSize=10"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	OK - The results of the given search.	None
400	Bad Request	Bad Request - The given input (request body or query parameter) is not valid.	None
401	Unauthorized	Unauthorized - The request requires authentication to access the resource.	None
403	Forbidden	Forbidden - The authenticated request requires permissions to access the resource.	None
406	Not Acceptable	Not Acceptable - There is no representation of the resource for the given accept header.	None
422	Unprocessable Entity	Unprocessable Content - The execution of the search failed (e.g. result size > max count).	None
500	Internal Server Error	Internal Server Error - The execution of this request caused an unexpected error.	None

`POST /data/search/{name}`

Execute the given CUSTOMIZED search configuration and wait for the results.

The values of the date fields of type Date, Date with time, Time should all be sent using the yyyy-MM-dd'T'HH:mm:ssZ format. The time part will be ignored for the Date type.

Body parameter

JSON

{
  "search": {
    "reference": {
      "type": "CORE_TEMPLATE",
      "name": "Person"
    },
    "filters": [
      {
        "name": "FirstName",
        "value": "John",
        "condition": "EQUALS"
      },
      {
        "name": "LastName",
        "value": "Smith",
        "condition": "EQUALS"
      }
    ]
  },
  "result": {
    "reference": {
      "type": "CORE_TEMPLATE",
      "name": "Person"
    },
    "filters": [],
    "columns": {
      "fields": [
        "FirstName",
        "LastName"
      ],
      "sort": [
        "FirstName|ASC",
        "LastName|DESC"
      ]
    }
  }
}

Parameters

Name	In	Type	Required	Description
name	path	string	true	The name of the search configuration
page	query	integer(int32)	false	The page index (1..N)
pageSize	query	integer(int32)	false	The size of the page to be returned
tenantId	query	integer(int32)	true	The tenant ID
body	body	SearchRequest	false	The search request

Example responses

OK - The results of the given search.

JSON

{
  "meta": {
    "name": "SearchConfigPersons",
    "date": "2025-06-05T14:49:48",
    "totalSize": 40,
    "page": 2,
    "pageSize": 10
  },
  "result": {
    "reference": {
      "type": "CORE_TEMPLATE",
      "name": "Person"
    },
    "rows": [
      {
        "FirstName": "John",
        "LastName": "Smith"
      }
    ]
  },
  "links": [
    {
      "rel": "self",
      "href": "/data/search/SearchConfigPersons?page=2&pageSize=10"
    },
    {
      "rel": "describedBy",
      "href": "/data/resources/search/SearchConfigPersons"
    },
    {
      "rel": "previous",
      "href": "/data/search/SearchConfigPersons?page=1&pageSize=10"
    },
    {
      "rel": "next",
      "href": "/data/search/SearchConfigPersons?page=3&pageSize=10"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	OK - The results of the given search.	None
400	Bad Request	Bad Request - The given input (request body or query parameter) is not valid.	None
401	Unauthorized	Unauthorized - The request requires authentication to access the resource.	None
403	Forbidden	Forbidden - The authenticated request requires permissions to access the resource.	None
406	Not Acceptable	Not Acceptable - There is no representation of the resource for the given accept header.	None
415	Unsupported Media Type	Unsupported Media Type - A request body of the given media type is not supported.	None
422	Unprocessable Entity	Unprocessable Content - The execution of the search failed (e.g. result size > max count).	None
500	Internal Server Error	Internal Server Error - The execution of this request caused an unexpected error.	None

`POST /data/async-search/{name}`

Trigger the asynchronous execution of the given CUSTOMIZED search configuration.

The values of the date fields of type Date, Date with time, Time should all be sent using the yyyy-MM-dd'T'HH:mm:ssZ format. The time part will be ignored for the Date type.

Body parameter

JSON

{
  "search": {
    "reference": {
      "type": "CORE_TEMPLATE",
      "name": "Person"
    },
    "filters": [
      {
        "name": "FirstName",
        "value": "John",
        "condition": "EQUALS"
      },
      {
        "name": "LastName",
        "value": "Smith",
        "condition": "EQUALS"
      }
    ]
  },
  "result": {
    "reference": {
      "type": "CORE_TEMPLATE",
      "name": "Person"
    },
    "filters": [],
    "columns": {
      "fields": [
        "FirstName",
        "LastName"
      ],
      "sort": [
        "FirstName|ASC",
        "LastName|DESC"
      ]
    }
  }
}

Parameters

Name	In	Type	Required	Description
name	path	string	true	The name of the search configuration
page	query	integer(int32)	false	The page index (1..N)
pageSize	query	integer(int32)	false	The size of the page to be returned
tenantId	query	integer(int32)	true	The tenant ID
body	body	SearchRequest	false	The search request

Example responses

202 Response

"55b78e0e-1623-4549-9e86-1c2287d50968"

Responses

Status	Meaning	Description	Schema
202	Accepted	Accepted - A search order has been initiated. Retrieve the results at the indicated location.	None
400	Bad Request	Bad Request - The given input (request body or query parameter) is not valid.	None
401	Unauthorized	Unauthorized - The request requires authentication to access the resource.	None
403	Forbidden	Forbidden - The authenticated request requires permissions to access the resource.	None
406	Not Acceptable	Not Acceptable - There is no representation of the resource for the given accept header.	None
415	Unsupported Media Type	Unsupported Media Type - A request body of the given media type is not supported.	None
500	Internal Server Error	Internal Server Error - The execution of this request caused an unexpected error.	None
507	Insufficient Storage	Insufficient Storage - Currently, there is no memory availabe to hold the results of the asynchronous search.	None

`GET /data/async-search/{name}/result-set/{uuid}`

Get the results of an asynchronous search.

Parameters

Name	In	Type	Required	Description
name	path	string	true	The name of the search configuration
uuid	path	string(uuid)	true	The UUID from the asynchronous search execution
tenantId	query	integer(int32)	true	The tenant ID

Example responses

OK - The result of the asynchronous search.

JSON

{
  "meta": {
    "name": "SearchConfigPersons",
    "date": "2025-06-05T14:49:48",
    "totalSize": 40,
    "page": 2,
    "pageSize": 10
  },
  "result": {
    "reference": {
      "type": "CORE_TEMPLATE",
      "name": "Person"
    },
    "rows": [
      {
        "FirstName": "John",
        "LastName": "Smith"
      }
    ]
  },
  "links": [
    {
      "rel": "self",
      "href": "/data/search/SearchConfigPersons?page=2&pageSize=10"
    },
    {
      "rel": "describedBy",
      "href": "/data/resources/search/SearchConfigPersons"
    },
    {
      "rel": "previous",
      "href": "/data/search/SearchConfigPersons?page=1&pageSize=10"
    },
    {
      "rel": "next",
      "href": "/data/search/SearchConfigPersons?page=3&pageSize=10"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	OK - The result of the asynchronous search.	None
400	Bad Request	Bad Request - The given input (request body or query parameter) is not valid.	None
401	Unauthorized	Unauthorized - The request requires authentication to access the resource.	None
403	Forbidden	Forbidden - The authenticated request requires permissions to access the resource.	None
406	Not Acceptable	Not Acceptable - There is no representation of the resource for the given accept header.	None
409	Conflict	Conflict - The asynchronous search is still ongoing. Retry after the suggest time.	None
410	Gone	Gone - The asynchronous search is not available anymore.	None
416	Range Not Satisfiable	Range Not Satisfiable - The result does not belong to the given asynchronous search.	None
422	Unprocessable Entity	Unprocessable Content - The execution of the search failed (e.g. result size > max count).	None
500	Internal Server Error	Internal Server Error - The execution of this request caused an unexpected error.	None

`DELETE /data/async-search/{name}/result-set/{uuid}`

Remove the result of an asynchronous search immediately.

Parameters

Name	In	Type	Required	Description
name	path	string	true	The name of the search configuration
uuid	path	string(uuid)	true	The UUID from the asynchronous search execution
tenantId	query	integer(int32)	true	The tenant ID

Responses

Status	Meaning	Description	Schema
204	No Content	No Content - The results are successfully removed.	None
400	Bad Request	Bad Request - The given input (request body or query parameter) is not valid.	None
401	Unauthorized	Unauthorized - The request requires authentication to access the resource.	None
403	Forbidden	Forbidden - The authenticated request requires permissions to access the resource.	None
406	Not Acceptable	Not Acceptable - There is no representation of the resource for the given accept header.	None
416	Range Not Satisfiable	Range Not Satisfiable - The result does not belong to the given asynchronous search.	None
500	Internal Server Error	Internal Server Error - The execution of this request caused an unexpected error.	None

`GET /data/resources/search`

List the available searches.

Parameters

Name	In	Type	Required	Description
tenantId	query	integer(int32)	true	The tenant ID

Example responses

OK - The available searches.

JSON

{
  "links": [
    {
      "rel": "self",
      "href": "/data/resources/search"
    }
  ],
  "content": [
    {
      "name": "SearchConfigPersons",
      "links": [
        {
          "rel": "describedBy",
          "href": "/data/resources/search/SearchConfigPersons"
        },
        {
          "rel": "search",
          "href": "/data/search/SearchConfigPersons?page,pageSize"
        },
        {
          "rel": "search",
          "href": "/data/async-search/SearchConfigPersons?page,pageSize"
        }
      ]
    },
    {
      "name": "SearchConfigCertificates",
      "links": [
        {
          "rel": "describedBy",
          "href": "/data/resources/search/SearchConfigCertificates"
        },
        {
          "rel": "search",
          "href": "/data/search/SearchConfigCertificates?page,pageSize"
        },
        {
          "rel": "search",
          "href": "/data/async-search/SearchConfigCertificates?page,pageSize"
        }
      ]
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	OK - The available searches.	None
401	Unauthorized	Unauthorized - The request requires authentication to access the resource.	None
403	Forbidden	Forbidden - The authenticated request requires permissions to access the resource.	None
406	Not Acceptable	Not Acceptable - There is no representation of the resource for the given accept header.	None
500	Internal Server Error	Internal Server Error - The execution of this request caused an unexpected error.	None

`GET /data/resources/search/{name}`

Get the configuration of the given search.

Parameters

Name	In	Type	Required	Description
name	path	string	true	The name of the search configuration
tenantId	query	integer(int32)	true	The tenant ID

Example responses

OK - The search configuration

JSON

{
  "search": {
    "reference": {
      "type": "CORE_TEMPLATE",
      "name": "Person"
    },
    "filters": [
      {
        "name": "FirstName",
        "value": "John",
        "condition": "EQUALS"
      },
      {
        "name": "LastName",
        "value": "Smith",
        "condition": "EQUALS"
      }
    ]
  },
  "result": {
    "reference": {
      "type": "CORE_TEMPLATE",
      "name": "Person"
    },
    "filters": [],
    "columns": {
      "fields": [
        "FirstName",
        "LastName"
      ],
      "sort": [
        "FirstName|ASC",
        "LastName|DESC"
      ]
    }
  },
  "links": [
    {
      "rel": "self",
      "href": "/data/resources/search/SearchConfigPersons"
    },
    {
      "rel": "search",
      "href": "/data/search/SearchConfigPersons?page,pageSize"
    },
    {
      "rel": "search",
      "href": "/data/async-search/SearchConfigPersons?page,pageSize"
    }
  ]
}

JSON

{
  "search": {
    "reference": {
      "type": "CORE_TEMPLATE",
      "name": "Person"
    },
    "filters": [
      {
        "name": "FirstName",
        "value": "John",
        "condition": "EQUALS"
      },
      {
        "name": "LastName",
        "value": "Smith",
        "condition": "EQUALS"
      }
    ]
  },
  "result": {
    "reference": {
      "type": "CORE_TEMPLATE",
      "name": "Person"
    },
    "filters": [],
    "columns": {
      "fields": [
        "FirstName",
        "LastName"
      ],
      "sort": [
        "FirstName|ASC",
        "LastName|DESC"
      ]
    }
  },
  "links": [
    {
      "rel": "self",
      "href": "/data/resources/search/SearchConfigPersons"
    },
    {
      "rel": "search",
      "href": "/data/search/SearchConfigPersons?page,pageSize"
    },
    {
      "rel": "search",
      "href": "/data/async-search/SearchConfigPersons?page,pageSize"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	OK - The search configuration	None
401	Unauthorized	Unauthorized - The request requires authentication to access the resource.	None
403	Forbidden	Forbidden - The authenticated request requires permissions to access the resource.	None
404	Not Found	Not Found - The desired resource does not exist.	None
406	Not Acceptable	Not Acceptable - There is no representation of the resource for the given accept header.	None
500	Internal Server Error	Internal Server Error - The execution of this request caused an unexpected error.	None