Safewhere Identify 5.20 REST API release notes

This document summarizes all changes made to Identify REST API in version 5.20.

Breaking changes

Default value of the OAuth connection's PerformSessionStatusNotification

This value is always True to allow OIDC clients to perform session status checks. With the addition of front-channel and back-channel logout, the default value of PerformSessionStatusNotification has changed as follows:

• If either a front-channel or back-channel logout URI is present, the default value of PerformSessionStatusNotification is False.
• Otherwise, the default value is True.

The default value for post_logout_redirect_uri

The default value for post_logout_redirect_uri is "https://client.example.com/loggedout". When the parameter is specified, its value is always validated, regardless of whether it is null or empty.

Connection endpoint

OAuth/OIDC application

Error messages now use correct field names for OAuth/OIDC applications when required parameters are missing or invalid.

Before	Current
OpenIdConnectLogoutRedirectUrl is invalid.	openIdLogoutRedirectUrl is invalid.
ClientId is invalid.	clientId is invalid.
ClientSecret is invalid.	clientSecret is invalid.
ApplicationName is invalid.	appName is invalid.
ApplicationAudience is invalid.	appAudience is invalid.
SymmetricSigningKey is invalid.	symmetricSigningKey is invalid.
RedirectUris is invalid.	redirectUris is invalid.
SectorIdentifierUri is invalid.	sectorIdentifierUri is invalid.
AppLogoUrl is invalid.	appLogoUrl is invalid.

The OAuth Identity Provider configuration model includes some new attributes:

• idTokenSigningAlgorithm
• idTokenKeyTransportAlgorithm
• idTokenEncryptionMethod
• frontChannelLogoutUri
• backChannelLogoutUri

{
  ...,
  "configurations": [
    {
      ...,
      "idTokenSigningAlgorithm": "RS256",
      "idTokenKeyTransportAlgorithm": "",
      "idTokenEncryptionMethod": "",
      "frontChannelLogoutUri": "",
      "backChannelLogoutUri": "",
      ...
    }
  ],
  ...
}

• Affected operations: GET /api/rest/v2/connections, POST /api/rest/v2/connections, PUT /api/rest/v2/connections, GET /api/rest/v2/connections/.filter, GET /api/rest/v2/connections/{connectionName}.

• Behaviors:

Name	Data type	Require?	Default value	Description
idTokenSigningAlgorithm	string	⬜️	RS256	This setting specifies the algorithm used to sign the ID token, which is a JSON Web Token (JWT). Supported algorithms include RS256, RS384, RS512, PS256, PS384 and PS512. Default value is RS256.
idTokenKeyTransportAlgorithm	string	⬜️	Empty	This setting indicates the algorithm used to encrypt the key used in the ID token encryption. Supported algorithms include RSA-OAEP, RSA-OAEP-256, A128KW, A192KW, and A256KW.
idTokenEncryptionMethod	string	⬜️	Empty	This setting defines the method used to encrypt the ID token. It specifies how the token's payload is encrypted to ensure confidentiality. Supported algorithms include A128CBC-HS256, A192CBC-HS384, A256CBC-HS512, A128GCM, A192GCM and A256GCM.
frontChannelLogoutUri	string	⬜️	Empty	This is the URL to which the user's browser is redirected when a logout is initiated. It's part of the Front-Channel Logout mechanism, must be an absolute URI. Note that the wildcard domain is not allowed.
backChannelLogoutUri	string	⬜️	Empty	This URL is used in the Back-Channel Logout mechanism. When a logout is initiated, the identity provider sends an HTTP POST request to this URL to notify the application that the user's session should be terminated. It must be an absolute URI. Note that the wildcard domain is not allowed.

Upload metadata

Added support for one additional property in UploadMetaDataReference: EntityIdentifierToUseWhenMetadataIsEntitiesDescriptor.

{
  ...,
  "uploadMetaDataReference": {
    ...,
    "entityIdentifierToUseWhenMetadataIsEntitiesDescriptor": "",
    ...
  },
  ...
}

• Affected operations: POST /api/rest/v2/connections, PUT /api/rest/v2/connections when the uploadMetaDataReference object is included in the request body.

• Behaviors:

Name	Data type	Require?	Default value	Description
entityIdentifierToUseWhenMetadataIsEntitiesDescriptor	string	⬜️	Empty	Specifies the entityID to use when the uploaded metadata is an EntitiesDescriptor containing multiple EntityDescriptor entries. This allows the system to locate and select the correct EntityDescriptor based on the provided entityID.

Audit logs endpoints

Support new endpoint to retrieve retained audit users

New GET /api/rest/v2/auditlogs/auditretainedusers endpoint with these parameters: fromDate, toDate, searchData, pageIndex, pageSize, sortBy, and sortOrder.

• Affected operation: GET /api/rest/v2/auditlogs/auditretainedusers.
• Required role(s): MonitorObserver.
• Supported parameters:

Name	Data type	Require?	Default value	Description
fromDate	string	⬜️	Empty	Used to filter data from a starting date. Format: dd/MM/yyyy HH:mmZ.
toDate	string	⬜️	Empty	Used to filter data up to an ending date. Format: dd/MM/yyyy HH:mmZ.
searchData	string	⬜️	Empty	Used to filter data by username.
pageIndex	number	⬜️	1	Index of the page that contains returned objects. If pageIndex is 0 or invalid, it is set to 1.
pageSize	number	⬜️	1000	Number of objects returned per page. If pageSize is 0 or invalid, it is set to 1000. Maximum value is 5000. If pageSize > 5000, it is set to 5000.
sortBy	string	⬜️	utcdate	Used to sort the returned objects. Supported value is utcdate. If sortBy is blank or invalid, the default value utcdate is used.
sortOrder	string	⬜️	Ascending	Sort order of returned objects: Ascending or Descending. If Descending is specified, results are sorted in descending order; otherwise, ascending order is used.

New user model for the GET /api/rest/v2/auditlogs/auditretainedusers endpoint.

• Affected operation: GET /api/rest/v2/auditlogs/auditretainedusers.

{
    "totalResults": 2,
    "pageIndex": 1,
    "pageSize": 20,
    "sortBy": "utcTimestamp",
    "sortOrder": "Ascending",
    "resources": [{
            "auditEventId": "18328",
            "entityId": "1bbd101d-a6cd-4d70-ab5d-67d7da214460",
            "enabled": true,
            "username": "user01",
            "author": "admin",
            "claims": [{
                    "claimType": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
                    "value": "user01"
                }
            ],
            "eventType": "RetainedUser",
            "utcTimestamp": "23/06/2026 09:47:36",
            "id": "2115",
            "externalId": null,
            "meta": null,
            "name": null,
            "description": null,
            "endpoint": null,
            "schema": "urn:scim:schemas:core:2.0:",
            "schemaExtensions": null,
            "schemaExtensionsDetail": null
        }, {
            "auditEventId": "18331",
            "entityId": "cb86f3a4-a591-48b7-87cd-db96e9bd1eb7",
            "enabled": true,
            "username": "user02",
            "author": "admin",
            "claims": [{
                    "claimType": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
                    "value": "user02"
                }, {
                    "claimType": "urn:identify:rest-api:role",
                    "value": "Observer"
                }
            ],
            "eventType": "RetainedUser",
            "utcTimestamp": "23/06/2026 09:52:00",
            "id": "2117",
            "externalId": null,
            "meta": null,
            "name": null,
            "description": null,
            "endpoint": null,
            "schema": "urn:scim:schemas:core:2.0:",
            "schemaExtensions": null,
            "schemaExtensionsDetail": null
        }
    ]
}

• Behaviors:

  Name	Data type	Description
  utcTimestamp	string	The datetime in UTC that the user has been retained
  eventType	string	Its value is always RetainedUser
  entityId	string	The user's ID
  enabled	boolean	If true, the user is enabled; if false, the user is disabled
  active	boolean	Indicates whether the user is active
  username	string	The user's username
  author	string	The user responsible for retaining this user
  claims	object	The user's claims information

User endpoint

Restore deleted user

Restores a previously deleted user from audit logs along with their associated data and second-factor authentication settings.

New POST /api/rest/v2/restoredeleteduser endpoint.

• Affected operation: POST /api/rest/v2/restoredeleteduser.
• Required role(s): UserContributor.
• Supported parameters:

Name	Data type	Require?	Default value	Description
userId	string	✅	Empty	The ID of a user to restore.

URL sample:

POST /api/rest/v2/restoredeleteduser?userId=43db1d50-b365-48d7-a466-20b0f13e914f