Additional and custom attributes in REST responses

In addition to the method-specific response data, the Loginapp REST API provides additional and custom attributes in many REST responses as follows:

  • Additional attributes are determined by the state of the flow engine, as indicated by the nextStep code in the response. Additional attributes provide relevant information about the current step and serve to provide the user with additional information in the Loginapp UI or in a REST client.
  • Custom attributes depend on the configuration of the step. Custom attributes may be configured in situations where a REST client requires information that goes beyond the standard use cases.
 
Example

Example of additional attributes: The REST response in an mTAN verification step used in an authentication flow returns the following additional attributes:

"attributes": {
  "nextAuthStep": "MTAN_OTP_REQUIRED",
  "phoneNumber": "+4123456789",
  "resendPossible": true,
  "customAttributes": {
    "myKey": "my value"
  }
}

The complete list of additional attributes is documented in the Loginapp REST API Reference. It lists all the additional attributes provided in the response for each next step code. For each type of REST API, a separate table with information about additional attributes has been added to the REST API documentation.

uiSettings block in REST responses

Additional and custom attributes are provided in the data block of the REST response. All custom clients should only use the attributes provided in the data block.

If UI settings are configured in Airlock IAM, every REST response contains an additional uiSettings block. This data is intended for the Loginapp UI and both additional and custom attributes are duplicated here. It is recommended that custom clients ignore the information provided in the uiSettings block since it may change without notice.

Using additional and custom attributes in translations

The Loginapp UI allows using additional and custom attributes in all translations.

  • Both types of attributes can be embedded with double curly braces in a translation.
  • Structured additional attributes must use a dot notation to reference the attribute.
  • Custom attributes are added as a structured attribute in the additionalAttributes block.
 
Example

Example: latestAuthentication is an additional attribute returned after a successful identity-providing step. Through configuration, a custom attribute named myKey is added to the REST response. The object has the following structure:

attributes: {
     latestAuthentication: {
        attemptAt: '..',
        successful: true 
      },
      customAttributes: {
        myKey: "my value"  
      }  
  }

To use the value from the additional and custom attributes in a translation, it is embedded as follows:

"Some text with placeholder {{latestAuthentication.attemptAt}} and {{customAttributes.myKey}} can be used."

Formatting additional and custom attributes

Additional attributes and custom attributes are displayed as the REST API provides them.

The only exceptions are additional attributes and custom attributes of type date. The Loginapp UI formats all dates for the browser's locale and timezone.

Non-interactive steps

Non-interactive steps will never return a REST response. With regards to additional and custom attributes, non-interactive steps work as follows:

  • Additional attributes will never be provided by non-interactive steps.
  • Custom attributes will be collected and added to the REST response of the first interactive step.

If multiple non-interactive steps try to add the same custom attribute, the next step will override the previous ones.

Missing values in additional and custom attributes

The Loginapp UI shows the following behavior when values of additional attributes are missing:

  • If placeholder values are missing in a string, the Loginapp UI automatically removes the placeholder and displays the remaining text.
  • If a string consists only of a placeholder and its value is missing, the placeholder itself will be displayed.

Further information and links