1. OAA Runtime API
  2. Tasks
  3. Preferences

User Preferences are updated.

put

/oaa/runtime/preferences/v1

Updates user preferences for given user. It overwrites user's existing preferences.

Request

There are no request parameters for this operation.

Supported Media Types
Request Body - application/xml ()
Root Schema : schema
Type: object
Information about the user and user's challenge registration for each type of challenge factor.
Show Source
  • User's altername name that may be used in the user screens.
  • The default locale of the user. If not provided then a default value of "en_US" will be used.
  • User's display name that may be used in the user screens.
  • factorsRegistered
    Array of factor registration data for user.
  • GroupId / ApplicationId of the user whose preferences data is required. If this parameter is not present a value of "Default" is used.
  • Location of the secureImage. Example:/images/secureImage01.jpg. If system is configured to return the image path as a full URL, then following two properties need to be configured. 1.)oaa.preferences.prependBasePath = true (default is false), 2.)oaa.preferences.imageBasePath=. If system property oaa.preferences.prependBasePath = false, then only the location of the secureImage is returned as is. For set(post) only the relative path should be used and for get full URL will be returned if configured as above.
  • User preferred phrase string ex Hello World!
  • Immutable ID of the user in the external systems. If this is present, then it takes precedence over userId + groupId combination.
  • Unique identifier of the user. May be further qualified by groupId.
Nested Schema : factorsRegistered
Type: array
Array of factor registration data for user.
Show Source
  • FactorRegData
    Entry containing a factorName and map of keys and a values. Map of keys and values will contain attributes specific to that factor.
Nested Schema : FactorRegData
Type: object
Entry containing a factorName and map of keys and a values. Map of keys and values will contain attributes specific to that factor.
Show Source
  • factorAttributes
    Collection of attributes for a factor for this user.
  • Key of the factor. This is the name that should map to one of the available factors in the OAA system. This should be one of the enum name in challenge.type.enum. Examples are ChallengeEmail, ChallengeSMS, ChallengeOMATOTP, ChallangeYOTP and ChallengeFIDO2.
  • This is the name that should map to one of the available factors in the OAA system. This should be one of the enum name in challenge.type.enum. For Example if factor is email then factorName should be Email Challenge. Examples are Email Challenge, SMS Challenge, OMA TOTP Challenge, Yubikey OTP Challange and FIDO2 Challenge.
  • Is the factor is preferred factor for the user to challenge.
Nested Schema : factorAttributes
Type: array
Collection of attributes for a factor for this user.
Show Source
Nested Schema : PrefFactorAttribute
Type: object
A map represented as an array of entries.
Show Source
Nested Schema : factorAttributeValue
Type: array
Value of factor specific attribute. Multiple values can be specified in the array.
Show Source
Nested Schema : PrefFactorAttributeValue
Type: object
Attribute value of the factor.
Show Source
  • "Date time string in the format rfc3339 sec 5.6. https://tools.ietf.org/html/rfc3339#section-5.6"
  • Indicates if the factor attribute is enabled or not. By default, it is set as true.
  • Indicates if the value of the attribute is preferred over other similar values in the array.
  • Default Value: true
    Indicates if the given attribute is validated. Some attributes do not require validation hence this field is optional.
  • Default Value: true
    Indicates if the given attribute is verified. Some attributes do not require verification hence this field is optional.
  • Friendly name of the device.
  • Value of the factor attribute.
Request Body - application/json ()
Root Schema : schema
Type: object
Information about the user and user's challenge registration for each type of challenge factor.
Show Source
  • User's altername name that may be used in the user screens.
  • The default locale of the user. If not provided then a default value of "en_US" will be used.
  • User's display name that may be used in the user screens.
  • factorsRegistered
    Array of factor registration data for user.
  • GroupId / ApplicationId of the user whose preferences data is required. If this parameter is not present a value of "Default" is used.
  • Location of the secureImage. Example:/images/secureImage01.jpg. If system is configured to return the image path as a full URL, then following two properties need to be configured. 1.)oaa.preferences.prependBasePath = true (default is false), 2.)oaa.preferences.imageBasePath=. If system property oaa.preferences.prependBasePath = false, then only the location of the secureImage is returned as is. For set(post) only the relative path should be used and for get full URL will be returned if configured as above.
  • User preferred phrase string ex Hello World!
  • Immutable ID of the user in the external systems. If this is present, then it takes precedence over userId + groupId combination.
  • Unique identifier of the user. May be further qualified by groupId.
Nested Schema : factorsRegistered
Type: array
Array of factor registration data for user.
Show Source
  • FactorRegData
    Entry containing a factorName and map of keys and a values. Map of keys and values will contain attributes specific to that factor.
Nested Schema : FactorRegData
Type: object
Entry containing a factorName and map of keys and a values. Map of keys and values will contain attributes specific to that factor.
Show Source
  • factorAttributes
    Collection of attributes for a factor for this user.
  • Key of the factor. This is the name that should map to one of the available factors in the OAA system. This should be one of the enum name in challenge.type.enum. Examples are ChallengeEmail, ChallengeSMS, ChallengeOMATOTP, ChallangeYOTP and ChallengeFIDO2.
  • This is the name that should map to one of the available factors in the OAA system. This should be one of the enum name in challenge.type.enum. For Example if factor is email then factorName should be Email Challenge. Examples are Email Challenge, SMS Challenge, OMA TOTP Challenge, Yubikey OTP Challange and FIDO2 Challenge.
  • Is the factor is preferred factor for the user to challenge.
Nested Schema : factorAttributes
Type: array
Collection of attributes for a factor for this user.
Show Source
Nested Schema : PrefFactorAttribute
Type: object
A map represented as an array of entries.
Show Source
Nested Schema : factorAttributeValue
Type: array
Value of factor specific attribute. Multiple values can be specified in the array.
Show Source
Nested Schema : PrefFactorAttributeValue
Type: object
Attribute value of the factor.
Show Source
  • "Date time string in the format rfc3339 sec 5.6. https://tools.ietf.org/html/rfc3339#section-5.6"
  • Indicates if the factor attribute is enabled or not. By default, it is set as true.
  • Indicates if the value of the attribute is preferred over other similar values in the array.
  • Default Value: true
    Indicates if the given attribute is validated. Some attributes do not require validation hence this field is optional.
  • Default Value: true
    Indicates if the given attribute is verified. Some attributes do not require verification hence this field is optional.
  • Friendly name of the device.
  • Value of the factor attribute.
Back to Top

Response

Supported Media Types

201 Response

User preferences are updated.
Body ()
Root Schema : PreferencesResponse
Type: object
Show Source
Nested Schema : PrefAPIResponse
Type: object
Show Source
Nested Schema : schema
Type: object
Information about the user and user's challenge registration for each type of challenge factor.
Show Source
  • User's altername name that may be used in the user screens.
  • The default locale of the user. If not provided then a default value of "en_US" will be used.
  • User's display name that may be used in the user screens.
  • factorsRegistered
    Array of factor registration data for user.
  • GroupId / ApplicationId of the user whose preferences data is required. If this parameter is not present a value of "Default" is used.
  • Location of the secureImage. Example:/images/secureImage01.jpg. If system is configured to return the image path as a full URL, then following two properties need to be configured. 1.)oaa.preferences.prependBasePath = true (default is false), 2.)oaa.preferences.imageBasePath=. If system property oaa.preferences.prependBasePath = false, then only the location of the secureImage is returned as is. For set(post) only the relative path should be used and for get full URL will be returned if configured as above.
  • User preferred phrase string ex Hello World!
  • Immutable ID of the user in the external systems. If this is present, then it takes precedence over userId + groupId combination.
  • Unique identifier of the user. May be further qualified by groupId.
Nested Schema : factorsRegistered
Type: array
Array of factor registration data for user.
Show Source
  • FactorRegData
    Entry containing a factorName and map of keys and a values. Map of keys and values will contain attributes specific to that factor.
Nested Schema : FactorRegData
Type: object
Entry containing a factorName and map of keys and a values. Map of keys and values will contain attributes specific to that factor.
Show Source
  • factorAttributes
    Collection of attributes for a factor for this user.
  • Key of the factor. This is the name that should map to one of the available factors in the OAA system. This should be one of the enum name in challenge.type.enum. Examples are ChallengeEmail, ChallengeSMS, ChallengeOMATOTP, ChallangeYOTP and ChallengeFIDO2.
  • This is the name that should map to one of the available factors in the OAA system. This should be one of the enum name in challenge.type.enum. For Example if factor is email then factorName should be Email Challenge. Examples are Email Challenge, SMS Challenge, OMA TOTP Challenge, Yubikey OTP Challange and FIDO2 Challenge.
  • Is the factor is preferred factor for the user to challenge.
Nested Schema : factorAttributes
Type: array
Collection of attributes for a factor for this user.
Show Source
Nested Schema : PrefFactorAttribute
Type: object
A map represented as an array of entries.
Show Source
Nested Schema : factorAttributeValue
Type: array
Value of factor specific attribute. Multiple values can be specified in the array.
Show Source
Nested Schema : PrefFactorAttributeValue
Type: object
Attribute value of the factor.
Show Source
  • "Date time string in the format rfc3339 sec 5.6. https://tools.ietf.org/html/rfc3339#section-5.6"
  • Indicates if the factor attribute is enabled or not. By default, it is set as true.
  • Indicates if the value of the attribute is preferred over other similar values in the array.
  • Default Value: true
    Indicates if the given attribute is validated. Some attributes do not require validation hence this field is optional.
  • Default Value: true
    Indicates if the given attribute is verified. Some attributes do not require verification hence this field is optional.
  • Friendly name of the device.
  • Value of the factor attribute.

401 Response

Unauthorized

412 Response

Invalid input
Body ()
Root Schema : PrefAPIResponse
Type: object
Show Source

500 Response

Internal server error

503 Response

Service Unavailable
Back to Top

Examples

The following example shows a sample request and response for updating user preferences.

cURL Command to Update the User Preferences in JSON Format

curl --location --request PUT '<OAAService>/oaa/runtime/preferences/v1' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic <Base64Encoded(<username>:<password>)>' \
--data '{
    "userId": "user4",
    "groupId": "Default",
    "factorsRegistered": [
        {
            "factorAttributes": [
                {
                  "factorAttributeValue": [
                    {
                      "value": "user1@example.com",
                      "name": "Device1",
                      "isEnabled": true
                    }
                  ],
                  "factorAttributeName": "email"
                }
              ],
              "factorKey": "ChallengeEmail",
              "isPreferred": false
            },
            {
              "factorAttributes": [
                {
                  "factorAttributeValue": [
                    {
                      "value": "welcome",
                      "name": "Device1",
                      "isEnabled": true
                    }
                  ],
                  "factorAttributeName": "omatotpsecretkey"
                }
              ],
              "factorKey": "ChallengeOMATOTP",
              "isPreferred": false
            },
            {
              "factorAttributes": [
                {
                  "factorAttributeValue": [
                    {
                      "value": "+123456789000",
                      "name": "Device1",
                      "isEnabled": true
                    }
                  ],
                  "factorAttributeName": "mobile"
                }
              ],
              "factorKey": "ChallengeSMS",
              "isPreferred": false
            }
          ]
        }'

Sample Response in JSON Format

{
    "preferences": {
        "userId": "user1",
        "groupId": "Default",
        "factorsRegistered": [
            {
                "isPreferred": false,
                "factorName": "Oracle Mobile Authenticator",
                "factorKey": "ChallengeOMATOTP",
                "factorAttributes": [
                    {
                        "factorAttributeName": "omatotpsecretkey",
                        "factorAttributeValue": [
                            {
                                "value": "secret_key",
                                "name": "Device1",
                                "isEnabled": true
                            }
                        ]
                    }
                ]
            },
            {
                "isPreferred": false,
                "factorName": "Email Challenge",
                "factorKey": "ChallengeEmail",
                "factorAttributes": [
                    {
                        "factorAttributeName": "email",
                        "factorAttributeValue": [
                            {
                                "value": "user1@example.com",
                                "name": "Device1",
                                "isEnabled": true
                            }
                        ]
                    }
                ]
            },
            {
                "isPreferred": false,
                "factorName": "SMS Challenge",
                "factorKey": "ChallengeSMS",
                "factorAttributes": [
                    {
                        "factorAttributeName": "mobile",
                        "factorAttributeValue": [
                            {
                                "value": "+123456789000",
                                "name": "Device1",
                                "isEnabled": true
                            }
                        ]
                    }
                ]
            }
        ]
    },
    "message": {
        "responseCode": "200",
        "responseMessage": "User Preferences updated."
    }
}

cURL Command to Update the User Preferences in XML Format

curl --location --request PUT '<OAAService>/oaa/runtime/preferences/v1' \
--header 'Content-Type: application/xml' \
--header 'Accept: application/xml' \
--header 'Authorization: Basic <Base64Encoded(<username>:<password>)>' \
--data '<?xml version="1.0" encoding="UTF-8" ?>
 <UserPreferences>
  <userId>testuser1</userId>
  <groupId>financeapp4</groupId>
  <factorsRegistered>
    <factorAttributes>
      <factorAttributeValue>
        <value>5109962275</value>
        <name>mytotp-pref-api</name>
        <isEnabled>false</isEnabled>
      </factorAttributeValue>
      <factorAttributeName>omatotpsecretkey</factorAttributeName>
    </factorAttributes>
    <factorKey>ChallengeOMATOTP</factorKey>
    <isPreferred>false</isPreferred>
  </factorsRegistered>
  </UserPreferences>
'

Sample Response in XML Format

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<PreferencesResponse>
    <preferences>
        <userId>testuser1</userId>
        <groupId>financeapp4</groupId>
        <factorsRegistered>
            <isPreferred>false</isPreferred>
            <factorName>Oracle Mobile Authenticator</factorName>
            <factorKey>ChallengeOMATOTP</factorKey>
            <factorAttributes>
                <factorAttributeName>omatotpsecretkey</factorAttributeName>
                <factorAttributeValue>
                    <value>5109962275</value>
                    <isPreferred>false</isPreferred>
                    <isVerified>true</isVerified>
                    <isValidated>true</isValidated>
                    <name>mytotp-pref-api</name>
                    <isEnabled>false</isEnabled>
                    <createTime>
                        <dateTime>2023-09-05T19:40:25.649Z</dateTime>
                        <parseFailed>false</parseFailed>
                        <rawParam>2023-09-05T19:40:25.649Z</rawParam>
                    </createTime>
                </factorAttributeValue>
            </factorAttributes>
        </factorsRegistered>
    </preferences>
    <message>
        <responseCode>200</responseCode>
        <responseMessage>User Preferences updated.</responseMessage>
    </message>
</PreferencesResponse>
Back to Top