OAA Runtime API

Synchronize the preferences of the user

put

/oaa/runtime/preferences/v1/sync

User preferences will be synchronized with the data present in the request. OAA must already have user info present along with factor and its required info. If factor is already registered and same data in present then the data will be overriden. However, if new data is provided for the existing factor, then, this API will add new device with the given "name" parameter. Also in case of missing friendly name, it will generate a new name for the device being registered. Other parameters include isEnabled, isPreferred and isVerified for a device can also be provided as boolean values.

The API call must include userId and groupId. If uniqueUserId is provided, It is used to uniquely identify the user. If uniqueUserId is not provided, the combination of userId and groupId is used to uniquely identify the user.

Request

There are no request parameters for this operation.

Supported Media Types

application/xml
application/json

Root Schema : schema

Type: object

Request object for synchronizing the preferences.

Show Source

attributes: array attributes

Attributes of the user
factorkey: string

The factor key for which it will be synced. 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.
groupId(required): string

GroupId / ApplicationId of the user. If this value is not present then Default will be used.
uniqueUserId: string

Immutable ID of the user in the external systems. If this is present, then it takes precedence over userId + groupId combination.
userId(required): string

Identifier of the user. May be further qualified by groupId.

{
    "type":"object",
    "description":"Request object for synchronizing the preferences.",
    "required":[
        "userId",
        "groupId"
    ],
    "properties":{
        "userId":{
            "description":"Identifier of the user. May be further qualified by groupId.",
            "type":"string"
        },
        "groupId":{
            "description":"GroupId / ApplicationId of the user. If this value is not present then Default will be used.",
            "type":"string"
        },
        "uniqueUserId":{
            "type":"string",
            "description":"Immutable ID of the user in the external systems. If this is present, then it takes precedence over userId + groupId combination."
        },
        "factorkey":{
            "type":"string",
            "description":"The factor key for which it will be synced. 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."
        },
        "attributes":{
            "type":"array",
            "description":"Attributes of the user",
            "items":{
                "$ref":"#/components/schemas/KeyValPair"
            }
        }
    }
}

Nested Schema : attributes

Type: array

Attributes of the user

Show Source

Array of: object KeyValPair

Key-value pair which can be used generically.

{
    "type":"array",
    "description":"Attributes of the user",
    "items":{
        "$ref":"#/components/schemas/KeyValPair"
    }
}

Nested Schema : KeyValPair

Type: object

Key-value pair which can be used generically.

Show Source

key(required): string

Key that can be used to fetch the related value.
value(required): object value

associated value.

{
    "required":[
        "key",
        "value"
    ],
    "type":"object",
    "properties":{
        "key":{
            "type":"string",
            "description":"Key that can be used to fetch the related value."
        },
        "value":{
            "type":"object",
            "description":"associated value."
        }
    },
    "description":"Key-value pair which can be used generically."
}

Nested Schema : value

Type: object

associated value.

Root Schema : schema

Type: object

Request object for synchronizing the preferences.

Show Source

attributes: array attributes

Attributes of the user
factorkey: string

The factor key for which it will be synced. 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.
groupId(required): string

GroupId / ApplicationId of the user. If this value is not present then Default will be used.
uniqueUserId: string

Immutable ID of the user in the external systems. If this is present, then it takes precedence over userId + groupId combination.
userId(required): string

Identifier of the user. May be further qualified by groupId.

{
    "type":"object",
    "description":"Request object for synchronizing the preferences.",
    "required":[
        "userId",
        "groupId"
    ],
    "properties":{
        "userId":{
            "description":"Identifier of the user. May be further qualified by groupId.",
            "type":"string"
        },
        "groupId":{
            "description":"GroupId / ApplicationId of the user. If this value is not present then Default will be used.",
            "type":"string"
        },
        "uniqueUserId":{
            "type":"string",
            "description":"Immutable ID of the user in the external systems. If this is present, then it takes precedence over userId + groupId combination."
        },
        "factorkey":{
            "type":"string",
            "description":"The factor key for which it will be synced. 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."
        },
        "attributes":{
            "type":"array",
            "description":"Attributes of the user",
            "items":{
                "$ref":"#/components/schemas/KeyValPair"
            }
        }
    }
}

Nested Schema : attributes

Type: array

Attributes of the user

Show Source

Array of: object KeyValPair

Key-value pair which can be used generically.

{
    "type":"array",
    "description":"Attributes of the user",
    "items":{
        "$ref":"#/components/schemas/KeyValPair"
    }
}

Nested Schema : KeyValPair

Type: object

Key-value pair which can be used generically.

Show Source

key(required): string

Key that can be used to fetch the related value.
value(required): object value

associated value.

{
    "required":[
        "key",
        "value"
    ],
    "type":"object",
    "properties":{
        "key":{
            "type":"string",
            "description":"Key that can be used to fetch the related value."
        },
        "value":{
            "type":"object",
            "description":"associated value."
        }
    },
    "description":"Key-value pair which can be used generically."
}

Nested Schema : value

Type: object

associated value.

Response

Supported Media Types

application/xml
application/json
text/plain

201 Response

User preferences are synchronized.

Root Schema : PreferencesResponse

Type: object

Show Source

message: object PrefAPIResponse
preferences: object schema

Information about the user and user's challenge registration for each type of challenge factor.

{
    "type":"object",
    "properties":{
        "preferences":{
            "$ref":"#/components/schemas/UserPreferences"
        },
        "message":{
            "$ref":"#/components/schemas/PrefAPIResponse"
        }
    }
}

Nested Schema : PrefAPIResponse

Type: object

Show Source

responseCode: string
responseMessage: string

{
    "type":"object",
    "properties":{
        "responseCode":{
            "type":"string"
        },
        "responseMessage":{
            "type":"string"
        }
    }
}

Nested Schema : schema

Type: object

Information about the user and user's challenge registration for each type of challenge factor.

Show Source

alternateName: string

User's altername name that may be used in the user screens.
defaultlocale: string

The default locale of the user. If not provided then a default value of "en_US" will be used.
displayName: string

User's display name that may be used in the user screens.
factorsRegistered: array factorsRegistered

Array of factor registration data for user.
groupId(required): string

GroupId / ApplicationId of the user whose preferences data is required. If this parameter is not present a value of "Default" is used.
imageReference: string

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.
phraseString: string

User preferred phrase string ex Hello World!
uniqueUserId: string

Canonical ID of the user. If this is present, then it takes precedence over userId + groupId combination.
userId(required): string

Identifier of the user. May be further qualified by groupId.

{
    "type":"object",
    "description":"Information about the user and user's challenge registration for each type of challenge factor.",
    "required":[
        "userId",
        "groupId"
    ],
    "properties":{
        "userId":{
            "description":"Identifier of the user. May be further qualified by groupId.",
            "type":"string"
        },
        "groupId":{
            "type":"string",
            "description":"GroupId / ApplicationId of the user whose preferences data is required. If this parameter is not present a value of \"Default\" is used."
        },
        "uniqueUserId":{
            "type":"string",
            "description":"Canonical ID of the user. If this is present, then it takes precedence over userId + groupId combination."
        },
        "defaultlocale":{
            "type":"string",
            "description":"The default locale of the user. If not provided then a default value of \"en_US\" will be used."
        },
        "displayName":{
            "type":"string",
            "description":"User's display name that may be used in the user screens."
        },
        "alternateName":{
            "type":"string",
            "description":"User's altername name that may be used in the user screens."
        },
        "imageReference":{
            "type":"string",
            "description":"Location of the secureImage. Example:/images/secureImage01.jpg.\nIf system is configured to return the image path as a full URL, then following two properties need to be configured. \n1.)oaa.preferences.prependBasePath = true (default is false),\n2.)oaa.preferences.imageBasePath=<base path of the URL>.\nIf system property oaa.preferences.prependBasePath = false, then only the location of the secureImage is returned as is.\nFor set(post) only the relative path should be used and for get full URL will be returned if configured as above.\n"
        },
        "phraseString":{
            "type":"string",
            "description":"User preferred phrase string ex Hello World!"
        },
        "factorsRegistered":{
            "description":"Array of factor registration data for user.",
            "type":"array",
            "items":{
                "$ref":"#/components/schemas/FactorRegData"
            }
        }
    }
}

Nested Schema : factorsRegistered

Type: array

Array of factor registration data for user.

Show Source

Array of: object FactorRegData

Entry containing a factorName and map of keys and a values. Map of keys and values will contain attributes specific to that factor.

{
    "description":"Array of factor registration data for user.",
    "type":"array",
    "items":{
        "$ref":"#/components/schemas/FactorRegData"
    }
}

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(required): array factorAttributes

Collection of attributes for a factor for this user.
factorKey: string

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.
factorName(required): string

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.
isPreferred: boolean

Is the factor is preferred factor for the user to challenge.

{
    "type":"object",
    "required":[
        "factorName",
        "factorAttributes"
    ],
    "description":"Entry containing a factorName and map of keys and a values.  Map of keys and values will contain attributes specific to that factor.",
    "properties":{
        "isPreferred":{
            "type":"boolean",
            "description":"Is the factor is preferred factor for the user to challenge."
        },
        "factorName":{
            "type":"string",
            "description":"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."
        },
        "factorKey":{
            "type":"string",
            "description":"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."
        },
        "factorAttributes":{
            "type":"array",
            "description":"Collection of attributes for a factor for this user.",
            "items":{
                "$ref":"#/components/schemas/PrefFactorAttribute"
            }
        }
    }
}

Nested Schema : factorAttributes

Type: array

Collection of attributes for a factor for this user.

Show Source

Array of: object PrefFactorAttribute

A map represented as an array of entries.

{
    "type":"array",
    "description":"Collection of attributes for a factor for this user.",
    "items":{
        "$ref":"#/components/schemas/PrefFactorAttribute"
    }
}

Nested Schema : PrefFactorAttribute

Type: object

A map represented as an array of entries.

Show Source

factorAttributeName: string

Name of factor specific attribute.
factorAttributeValue: array factorAttributeValue

Value of factor specific attribute. Multiple values can be specified in the array.

{
    "type":"object",
    "description":"A map represented as an array of entries.",
    "properties":{
        "factorAttributeName":{
            "type":"string",
            "description":"Name of factor specific attribute."
        },
        "factorAttributeValue":{
            "type":"array",
            "items":{
                "$ref":"#/components/schemas/PrefFactorAttributeValue"
            },
            "description":"Value of factor specific attribute. Multiple values can be specified in the array."
        }
    }
}

Nested Schema : factorAttributeValue

Type: array

Value of factor specific attribute. Multiple values can be specified in the array.

Show Source

Array of: object PrefFactorAttributeValue

Attribute value of the factor.

{
    "type":"array",
    "items":{
        "$ref":"#/components/schemas/PrefFactorAttributeValue"
    },
    "description":"Value of factor specific attribute. Multiple values can be specified in the array."
}

Nested Schema : PrefFactorAttributeValue

Type: object

Attribute value of the factor.

Show Source

createTime: string (date-time)

"Date time string in the format rfc3339 sec 5.6. https://tools.ietf.org/html/rfc3339#section-5.6"
isEnabled: boolean

Indicates if the factor attribute is enabled or not. By default, it is set as true.
isPreferred: boolean

Indicates if the value of the attribute is preferred over other similar values in the array.
isValidated: boolean

Default Value: true

Indicates if the given attribute is validated. Some attributes do not require validation hence this field is optional.
isVerified: boolean

Default Value: true

Indicates if the given attribute is verified. Some attributes do not require verification hence this field is optional.
name(required): string

Friendly name of the device.
value(required): string

Value of the factor attribute.

{
    "type":"object",
    "required":[
        "value",
        "name"
    ],
    "description":"Attribute value of the factor.",
    "properties":{
        "value":{
            "type":"string",
            "description":"Value of the factor attribute."
        },
        "isPreferred":{
            "type":"boolean",
            "description":"Indicates if the value of the attribute is preferred over other similar values in the array."
        },
        "isVerified":{
            "type":"boolean",
            "default":true,
            "description":"Indicates if the given attribute is verified. Some attributes do not require verification hence this field is optional."
        },
        "isValidated":{
            "type":"boolean",
            "default":true,
            "description":"Indicates if the given attribute is validated. Some attributes do not require validation hence this field is optional."
        },
        "name":{
            "type":"string",
            "description":"Friendly name of the device."
        },
        "isEnabled":{
            "type":"boolean",
            "description":"Indicates if the factor attribute is enabled or not. By default, it is set as true."
        },
        "createTime":{
            "$ref":"#/components/schemas/DateTime",
            "description":"Time of factor creation."
        }
    }
}

401 Response

Unauthorized

412 Response

Invalid input

Root Schema : PrefAPIResponse

Type: object

Show Source

responseCode: string
responseMessage: string

{
    "type":"object",
    "properties":{
        "responseCode":{
            "type":"string"
        },
        "responseMessage":{
            "type":"string"
        }
    }
}

500 Response

Internal server error

503 Response

Service Unavailable

Examples

The following example shows a sample request and response for synchronizing the preferences of the user.

cURL Command to Synchronize the User Preferences in JSON Format

curl --location --request PUT '<OAAService>/oaa/runtime/preferences/v1/sync' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic <Base64Encoded(<username>:<password>)>' \
--data '{
  "userId": "user1",
    "groupId": "financeapp",
    "uniqueUserId": "user1",
    "factorkey": "ChallengeEmail",
    "attributes": [
        {
            "key": "name",
            "value": "Device1"
        },
        {
            "key": "email",
            "value": "user1@example.com"
        },
        {
            "key": "isEnabled",
            "value": true
        },
        {
            "key": "isValidated",
            "value": true
        },
        {
            "key": "isPreferred",
            "value": false
        },
        {
            "key": "attr1",
            "value": "value1"
        },
        {
            "key": "attr2",
            "value": "val2"
        }
    ]
}'

Sample Response in JSON Format

{
    "preferences": {
        "userId": "user1",
        "groupId": "financeapp",
        "uniqueUserId": "user1",
        "imageReference": "/u01/oracle/service/store/img001.jpg",
        "phraseString": "Hello World!",
        "factorsRegistered": [
            {
                "isPreferred": false,
                "factorName": "Oracle Mobile Authenticator",
                "factorKey": "ChallengeOMATOTP",
                "factorAttributes": [
                    {
                        "factorAttributeName": "omatotpsecretkey",
                        "factorAttributeValue": [
                            {
                                "value": "secret_key",
                                "isPreferred": false,
                                "isVerified": true,
                                "isValidated": true,
                                "name": "Device1",
                                "isEnabled": true,
                                "createTime": {
                                    "parseFailed": false,
                                    "dateTime": "2025-03-07T20:31:43.782Z",
                                    "rawParam": "2025-03-07T20:31:43.782Z"
                                }
                            }
                        ]
                    }
                ]
            },
            {
                "isPreferred": false,
                "factorName": "Email Challenge",
                "factorKey": "ChallengeEmail",
                "factorAttributes": [
                    {
                        "factorAttributeName": "Device1",
                        "factorAttributeValue": [
                            {
                                "value": "true",
                                "isPreferred": false,
                                "isVerified": true,
                                "isValidated": true,
                                "name": "isValidated",
                                "isEnabled": true,
                                "createTime": {
                                    "parseFailed": false,
                                    "dateTime": "2025-03-07T20:31:43.783Z",
                                    "rawParam": "2025-03-07T20:31:43.783Z"
                                }
                            },
                            {
                                "value": "val2",
                                "isPreferred": false,
                                "isVerified": true,
                                "isValidated": true,
                                "name": "attr2",
                                "isEnabled": true,
                                "createTime": {
                                    "parseFailed": false,
                                    "dateTime": "2025-03-07T20:31:43.783Z",
                                    "rawParam": "2025-03-07T20:31:43.783Z"
                                }
                            },
                            {
                                "value": "value1",
                                "isPreferred": false,
                                "isVerified": true,
                                "isValidated": true,
                                "name": "attr1",
                                "isEnabled": true,
                                "createTime": {
                                    "parseFailed": false,
                                    "dateTime": "2025-03-07T20:31:43.783Z",
                                    "rawParam": "2025-03-07T20:31:43.783Z"
                                }
                            }
                        ]
                    },
                    {
                        "factorAttributeName": "email",
                        "factorAttributeValue": [
                            {
                                "value": "user1@example.com",
                                "isPreferred": false,
                                "isVerified": true,
                                "isValidated": true,
                                "name": "Device1",
                                "isEnabled": true,
                                "createTime": {
                                    "parseFailed": false,
                                    "dateTime": "2025-03-07T20:31:43.783Z",
                                    "rawParam": "2025-03-07T20:31:43.783Z"
                                }
                            }
                        ]
                    }
                ]
            }
        ]
    },
    "message": {
        "responseCode": "200",
        "responseMessage": "User Preferences updated."
    }
}

cURL Command to Synchronize the User Preferences in XML Format

curl --location --request PUT '<OAAService>/oaa/runtime/preferences/v1/sync' \
--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>user1</userId>
  <groupId>financeapp</groupId>
  <uniqueUserId>user1</uniqueUserId>
  <factorKey>ChallengeEmail</factorKey>
  <attributes>
    <key>name</key>
    <value>Device1</value>
  </attributes>
  <attributes>
    <key>email</key>
    <value>user1@example.com</value>
  </attributes>
  <attributes>
    <key>isEnabled</key>
    <value>true</value>
  </attributes>
  <attributes>
    <key>isValidated</key>
    <value>true</value>
  </attributes>
  <attributes>
    <key>isPreferred</key>
    <value>false</value>
  </attributes>
  <attributes>
    <key>attr1</key>
    <value>value1</value>
  </attributes>
  <attributes>
    <key>attr2</key>
    <value>val2</value>
  </attributes>
</UserPreferences>'

Sample Response in XML Format

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<PreferencesResponse>
  <preferences>
    <userId>user1</userId>
  <groupId>financeapp</groupId>
  <uniqueUserId>user1</uniqueUserId>
    <factorsRegistered>
      <isPreferred>false</isPreferred>
      <factorName>Email Challenge</factorName>
      <factorKey>ChallengeEmail</factorKey>
      <factorAttributes>
        <factorAttributeName>email</factorAttributeName>
        <factorAttributeValue>
          <value>user1@example.com</value>
          <name>Device1</name>
          <isEnabled>true</isEnabled>
          <isValidated>true</isValidated>
          <isPreferred>false</isPreferred>
        </factorAttributeValue>
      </factorAttributes>
      <factorAttributes>
        <factorAttributeName>Device1</factorAttributeName>
        <factorAttributeValue>
          <value>value1</value>
          <name>attr1</name>
          <isEnabled>true</isEnabled>
          <isValidated>true</isValidated>
          <isPreferred>false</isPreferred>
        </factorAttributeValue>
        <factorAttributeValue>
          <value>value2</value>
          <name>attr2</name>
          <isEnabled>true</isEnabled>
          <isValidated>true</isValidated>
          <isPreferred>false</isPreferred>
        </factorAttributeValue>
      </factorAttributes>
    </factorsRegistered>
  </preferences>
  <message>
    <responseCode>201</responseCode>
    <responseMessage>User preference is created.</responseMessage>
  </message>
</PreferencesResponse>