{ "openapi":"3.0.0", "info":{ "description":"REST API for OAA Runtime User Flows", "version":"2025.06.05", "title":"OAA Runtime API", "contact":{ "email":"ngssodev_us_grp@oracle.com" }, "license":{ "name":"Apache 2.0", "url":"http://www.apache.org/licenses/LICENSE-2.0.html" }, "x-summary":"REST API for OAA Runtime User Flows" }, "tags":[ { "name":"ChallengeCounter", "description":"ChallengeCounter will be reset based on provided context and challengeType.", "externalDocs":{ "description":"Find out more", "url":"http://oracle.com/oaa" } }, { "name":"ConfigProperty", "description":"Configuration Properties Management API for OAA Service.", "externalDocs":{ "description":"Find out more", "url":"http://oracle.com/oaa" } }, { "name":"KBA", "description":"API that allows verification of user identity based on private information of user.", "externalDocs":{ "description":"Find out more", "url":"https://docs.oracle.com/en/middleware/idm/advanced-authentication/oaaag/introducing-oaa.html" } }, { "name":"Preferences", "description":"OAA API for managing user challenge preferences. User Preferences data is used for challenge flows during user authentication.", "externalDocs":{ "description":"Find out more", "url":"http://oracle.com/oaa" } }, { "name":"SecretKey", "description":"API for creating TOTP secret key." }, { "name":"UAS runtime", "description":"UAS runtime api providing more simplified apis outside. Internally will call apis from UAS and Factor to limit the number of required calls. Find out more from the application.wadl which will be at http://:/uas/runtime/application.wadl", "externalDocs":{ "description":"Find out more", "url":"http://oracle.com/uas" } } ], "paths":{ "/oaa/runtime/totp/key/v1/":{ "post":{ "tags":[ "SecretKey" ], "operationId":"createSecretKey", "summary":"Create Secret Key", "description":"Use this API to create a TOTP secret key for a user.", "requestBody":{ "$ref":"#/components/requestBodies/CreateSecretKeyRequest" }, "responses":{ "201":{ "description":"Secret key has been created.", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/SecretKey" } }, "application/xml":{ "schema":{ "$ref":"#/components/schemas/SecretKey" } }, "text/plain":{ "schema":{ "$ref":"#/components/schemas/SecretKey" } } } }, "400":{ "description":"Bad Request" }, "401":{ "description":"Unauthorized" }, "403":{ "description":"Could not register secret key", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/SecretKeyAPIResponse" } }, "application/xml":{ "schema":{ "$ref":"#/components/schemas/SecretKeyAPIResponse" } }, "text/plain":{ "schema":{ "$ref":"#/components/schemas/SecretKeyAPIResponse" } } } }, "422":{ "description":"Requested user information not found", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/SecretKeyAPIResponse" } }, "application/xml":{ "schema":{ "$ref":"#/components/schemas/SecretKeyAPIResponse" } }, "text/plain":{ "schema":{ "$ref":"#/components/schemas/SecretKeyAPIResponse" } } } }, "500":{ "description":"Internal server error", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/SecretKeyAPIResponse" } }, "application/xml":{ "schema":{ "$ref":"#/components/schemas/SecretKeyAPIResponse" } }, "text/plain":{ "schema":{ "$ref":"#/components/schemas/SecretKeyAPIResponse" } } } }, "503":{ "description":"Service Unavailable", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/SecretKeyAPIResponse" } }, "application/xml":{ "schema":{ "$ref":"#/components/schemas/SecretKeyAPIResponse" } }, "text/plain":{ "schema":{ "$ref":"#/components/schemas/SecretKeyAPIResponse" } } } } }, "x-internal-id":"oaa-runtime-totp-key-v1--post", "x-filename-id":"oaa-runtime-totp-key-v1-post" } }, "/oaa/runtime/totp/registrationurl/v1/":{ "post":{ "tags":[ "SecretKey" ], "operationId":"createRegistrationUrl", "summary":"Create Registration URL", "description":"Use this API to generate a TOTP registration URL.", "requestBody":{ "$ref":"#/components/requestBodies/CreateTotpConfigRequest" }, "responses":{ "201":{ "description":"Registration URL has been created.", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/CreateTotpConfigResponse" } }, "application/xml":{ "schema":{ "$ref":"#/components/schemas/CreateTotpConfigResponse" } }, "text/plain":{ "schema":{ "$ref":"#/components/schemas/CreateTotpConfigResponse" } } } }, "400":{ "description":"Bad Request" }, "401":{ "description":"Unauthorized" }, "403":{ "description":"Could not create TOTP config" }, "422":{ "description":"Requested user information not found" }, "500":{ "description":"Internal server error" }, "503":{ "description":"Service Unavailable" } }, "x-internal-id":"oaa-runtime-totp-registrationurl-v1--post", "x-filename-id":"oaa-runtime-totp-registrationurl-v1-post" } }, "/challengecounter/v1":{ "delete":{ "tags":[ "ChallengeCounter" ], "summary":"OAA API resets Challenge counter for the given challegeType for the user based on the contextId", "description":"OAA API to reset the challenge counter. The contextId is used to locate the user. The returned ModelAPIResponse will consist of response code and response message. The challengeType and contextId are mandatory parameters. Error response will be returned if any of, challengeType or contextId are invalid.", "operationId":"resetChallengeCounter", "parameters":[ { "name":"contextId", "in":"query", "description":"Context Id of one the previous contexts that was returned in previous runtime responses from OAA. This is used to locate the right user and user's challenge data", "required":true, "style":"form", "explode":true, "schema":{ "type":"string" } }, { "name":"challengeType", "in":"query", "description":"This is the type or channel by which the user was challenged. It can be one of ChallengeEmail, ChallengeSMS, ChallengeOMATOTP, ChallengeYOTP or ChallengeFIDO2.", "required":true, "style":"form", "explode":true, "schema":{ "type":"string" } } ], "responses":{ "200":{ "description":"Challenge Counter is reset.", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/ModelAPIResponse" } }, "application/xml":{ "schema":{ "$ref":"#/components/schemas/ModelAPIResponse" } }, "text/plain":{ "schema":{ "$ref":"#/components/schemas/ModelAPIResponse" } } } }, "404":{ "description":"Invalid input. ContextId or ChallengeType was not found." }, "500":{ "description":"Internal server error" } }, "security":[ { "context_auth":[ "write:context", "read:context" ] } ], "x-internal-id":"challengecounter-v1-delete", "x-filename-id":"challengecounter-v1-delete" } }, "/config/property/v1":{ "get":{ "tags":[ "ConfigProperty" ], "summary":"Gets configuration properties such that all returned properties contain the property name provided in the input.", "description":"Gets configuration properties such that all returned properties contain the property name provided in the input. If there is no match to the input, then an empty propery array will be present in the output.", "operationId":"getConfigProperties", "parameters":[ { "name":"propertyName", "in":"query", "description":"Name to search for configuration property. All properties that contain the input name are returned in the response.", "required":true, "style":"form", "explode":true, "schema":{ "type":"string" } }, { "name":"locale", "in":"query", "description":"This optional parameter can be provided in the input, if value of the property is desired in certain locale. If service implementation has value defined for that property in that locale then that value will be returned. If the locale os not provided or if locale specific value is not available for input property value, then property vale in default locale (en_US) will be retuned in the output.", "required":false, "style":"form", "explode":true, "schema":{ "type":"string" } } ], "responses":{ "200":{ "description":"Success.", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/ConfigPropertiesResponse" } }, "application/xml":{ "schema":{ "$ref":"#/components/schemas/ConfigPropertiesResponse" } } } }, "406":{ "description":"Incorrect Data.", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/ConfigAPIResponse" } }, "application/xml":{ "schema":{ "$ref":"#/components/schemas/ConfigAPIResponse" } } } } }, "x-internal-id":"config-property-v1-get", "x-filename-id":"config-property-v1-get" }, "put":{ "tags":[ "ConfigProperty" ], "summary":"Creates or updates configuration properties that are provided in the input.", "description":"Returns created or updated properties.", "operationId":"setConfigProperties", "requestBody":{ "$ref":"#/components/requestBodies/ConfigPropertiesRequest" }, "responses":{ "200":{ "description":"Success", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/ConfigPropertiesResponse" } }, "application/xml":{ "schema":{ "$ref":"#/components/schemas/ConfigPropertiesResponse" } } } }, "406":{ "description":"Incorrect Data", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/ConfigAPIResponse" } }, "application/xml":{ "schema":{ "$ref":"#/components/schemas/ConfigAPIResponse" } } } } }, "x-internal-id":"config-property-v1-put", "x-filename-id":"config-property-v1-put" }, "delete":{ "tags":[ "ConfigProperty" ], "summary":"Deletes configuration property that is provided in the input.", "description":"Whether property to be deleted exists or not a 200 response is returned. If no config property is provided in the input then this is function does not change anything in config properties, and a 200 response is returned. Only properties that are stored in the persistent store can be deleted. Properties that are sourced from product files and product environment cannot be deleted using this API. This API returns API Response. API response contains empty array of properties in all cases.", "operationId":"deleteConfigProperty", "parameters":[ { "name":"propertyName", "in":"query", "description":"Property name to delete. Property with name that is exact match with the input will be deleted if possible.", "required":true, "style":"form", "explode":true, "schema":{ "type":"string" } } ], "responses":{ "200":{ "description":"Success", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/ConfigAPIResponse" } }, "application/xml":{ "schema":{ "$ref":"#/components/schemas/ConfigAPIResponse" } } } }, "406":{ "description":"Incorrect Data", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/ConfigAPIResponse" } }, "application/xml":{ "schema":{ "$ref":"#/components/schemas/ConfigAPIResponse" } } } } }, "x-internal-id":"config-property-v1-delete", "x-filename-id":"config-property-v1-delete" } }, "/authn/v1":{ "post":{ "tags":[ "UAS runtime" ], "summary":"Returns list of challenges available for the user.", "description":"Returns information about the challenges available for the user. If there is only one challenge option, the challenge can be initiated automatically.

API call should be made with canonical uniqueUserId along with userId and groups. The user record is fetched using the canonical uniqueUserId. If canonical uniqueUserId is not provided, the combination of userId and groups is used to locate the user.", "operationId":"getAuthnForUser", "requestBody":{ "$ref":"#/components/requestBodies/AuthnRequest" }, "responses":{ "200":{ "description":"Success", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/AuthnResponse" } }, "application/xml":{ "schema":{ "$ref":"#/components/schemas/AuthnResponse" } } } }, "400":{ "description":"if the authn request failed due to validation of parameters.", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/AuthnAPIResponse" } }, "application/xml":{ "schema":{ "$ref":"#/components/schemas/AuthnAPIResponse" } } } } }, "x-internal-id":"authn-v1-post", "x-filename-id":"authn-v1-post" }, "put":{ "tags":[ "UAS runtime" ], "summary":"Initialize or validate user challenge", "description":"Updates the authentication status in OAA. Returns information about whether the challenge is successful or if further challenge is required. Internally calls validate to verify the challenge data.

Along with correlationId, the API calls can be made with canonical uniqueUserId along with userId and groups. The combination of userId and groups is used to locate the user.", "operationId":"updateAuthnForUser", "requestBody":{ "$ref":"#/components/requestBodies/UpdateAuthnRequest" }, "responses":{ "200":{ "description":"Success", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/UpdateAuthnResponse" } }, "application/xml":{ "schema":{ "$ref":"#/components/schemas/UpdateAuthnResponse" } } } }, "400":{ "description":"if the update authn failed due to validation of parameters.", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/AuthnAPIResponse" } }, "application/xml":{ "schema":{ "$ref":"#/components/schemas/AuthnAPIResponse" } } } } }, "x-internal-id":"authn-v1-put", "x-filename-id":"authn-v1-put" } }, "/oaa/runtime/preferences/v1":{ "post":{ "tags":[ "Preferences" ], "operationId":"registerUserPreferences", "summary":"User Preferences are created/registered.", "description":"API to register user preferences. This API seeds user and his/her preferences in the OAA system. For data that is not consistent/complete, an error is returned.

If the client has canonical uniqueUserId that can uniquely identify the user, in all API calls that take canonical uniqueUserId, the canonical uniqueUserId should be provided. If the client does not have canonical uniqueUserId to identify the user, OAA system will generate the canonical id when user is created. In all subsequent API calls for that user, the generated canonical uniqueUserId should be provided for that user. If the provided canonical uniqueUserId already exists in the system, the API call will return HTTP response code 412.\n", "requestBody":{ "$ref":"#/components/requestBodies/UserPreferences" }, "responses":{ "201":{ "description":"User preferences are registered.", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/PreferencesResponse" } }, "application/xml":{ "schema":{ "$ref":"#/components/schemas/PreferencesResponse" } }, "text/plain":{ "schema":{ "$ref":"#/components/schemas/PreferencesResponse" } } } }, "401":{ "description":"Unauthorized" }, "412":{ "description":"Invalid input", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/PrefAPIResponse" } }, "application/xml":{ "schema":{ "$ref":"#/components/schemas/PrefAPIResponse" } }, "text/plain":{ "schema":{ "$ref":"#/components/schemas/PrefAPIResponse" } } } }, "500":{ "description":"Internal server error" }, "503":{ "description":"Service Unavailable" } }, "security":[ { "context_auth":[ "write:context", "read:context" ] } ], "x-internal-id":"oaa-runtime-preferences-v1-post", "x-filename-id":"oaa-runtime-preferences-v1-post" }, "get":{ "operationId":"getUserPreferences", "tags":[ "Preferences" ], "summary":"Deprecated - Returns user's challenge preferences as available in the OAA.", "description":"Deprecated:Please use fetchuserpreferencessecurely API. Returns a list of challenge preferences for user. Error is returned for user not found in the OAA. API call should be made with static and canonical uniqueUserId along with userId and groupId. If userId is static and canonical, the call can also be made using userId and groupId. If uniqueUserId is provided, userId and groupId is ignored.\n", "parameters":[ { "name":"userId", "description":"UserId or loginId of the user whose preferences data is required.", "in":"query", "required":true, "schema":{ "type":"string" } }, { "name":"groupId", "description":"GroupId / ApplicationId of the user whose preferences data is required. If this parameter is not present, then a value of \"Default\" is used.", "in":"query", "required":false, "schema":{ "type":"string" } }, { "name":"uniqueUserId", "description":"Immutable ID of the user in the external systems. If this is present, then it takes precedence over userId + groupId combination.", "in":"query", "required":false, "schema":{ "type":"string" } } ], "responses":{ "200":{ "description":"Success", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/UserPreferences" } }, "application/xml":{ "schema":{ "$ref":"#/components/schemas/UserPreferences" } } } }, "401":{ "description":"Unauthorized" }, "406":{ "description":"Requested user information not found", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/PrefAPIResponse" } }, "application/xml":{ "schema":{ "$ref":"#/components/schemas/PrefAPIResponse" } } } } }, "x-internal-id":"oaa-runtime-preferences-v1-get", "x-filename-id":"oaa-runtime-preferences-v1-get" }, "put":{ "tags":[ "Preferences" ], "operationId":"updateUserPreferences", "summary":"User Preferences are updated.", "description":"Updates the user's existing preferences. If the factor is already registered, it will be overwritten with the provided data. If not, the API will add it using the provided data. The optional parameters imageReference and phraseString, if provided, will overwrite any existing values. This API returns all of the user's preferences, including both the updated and existing ones.

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. An error is returned if the user is not found in OAA.", "requestBody":{ "$ref":"#/components/requestBodies/UserPreferences" }, "responses":{ "201":{ "description":"User preferences are updated.", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/PreferencesResponse" } }, "application/xml":{ "schema":{ "$ref":"#/components/schemas/PreferencesResponse" } }, "text/plain":{ "schema":{ "$ref":"#/components/schemas/PreferencesResponse" } } } }, "401":{ "description":"Unauthorized" }, "412":{ "description":"Invalid input", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/PrefAPIResponse" } }, "application/xml":{ "schema":{ "$ref":"#/components/schemas/PrefAPIResponse" } }, "text/plain":{ "schema":{ "$ref":"#/components/schemas/PrefAPIResponse" } } } }, "500":{ "description":"Internal server error" }, "503":{ "description":"Service Unavailable" } }, "security":[ { "context_auth":[ "write:context", "read:context" ] } ], "x-internal-id":"oaa-runtime-preferences-v1-put", "x-filename-id":"oaa-runtime-preferences-v1-put" }, "delete":{ "tags":[ "Preferences" ], "operationId":"deleteUserPreferences", "summary":"Deprecated - User Preferences are deleted.", "description":"Deprecated Please use deleteuserpreferencessecurely API.This API deletes user's preference for the given userid and group .", "parameters":[ { "name":"userId", "description":"UserId or loginId of the user whose preferences data is to be deleted.", "in":"query", "required":true, "schema":{ "type":"string" } }, { "name":"groupId", "description":"GroupId / ApplicationId of the user whose preferences data is to be deleted. If this parameter is not present then, a value of Default is used.", "in":"query", "required":false, "schema":{ "type":"string" } }, { "name":"uniqueUserId", "description":"Immutable ID of the user in the external systems. If this is present, then it takes precedence over userId + groupId combination.", "in":"query", "required":false, "schema":{ "type":"string" } }, { "name":"factorkey", "description":"factor key to be deleted in the user preference. This is optional field. If the field is missing then it all the factors in the user profile will be deleted.", "in":"query", "required":false, "schema":{ "type":"string" } }, { "name":"devicename", "description":"Name of the device to be deleted in the user preference associated with factorkey. This is optional field and must also have factorykey if this parameter is provided.", "in":"query", "required":false, "schema":{ "type":"string" } } ], "responses":{ "201":{ "description":"User preferences are deleted.", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/PrefAPIResponse" } }, "application/xml":{ "schema":{ "$ref":"#/components/schemas/PrefAPIResponse" } }, "text/plain":{ "schema":{ "$ref":"#/components/schemas/PrefAPIResponse" } } } }, "401":{ "description":"Unauthorized" }, "412":{ "description":"Invalid input", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/PrefAPIResponse" } }, "application/xml":{ "schema":{ "$ref":"#/components/schemas/PrefAPIResponse" } }, "text/plain":{ "schema":{ "$ref":"#/components/schemas/PrefAPIResponse" } } } }, "500":{ "description":"Internal server error" }, "503":{ "description":"Service Unavailable" } }, "security":[ { "context_auth":[ "write:context", "read:context" ] } ], "x-internal-id":"oaa-runtime-preferences-v1-delete", "x-filename-id":"oaa-runtime-preferences-v1-delete" } }, "/oaa/runtime/preferences/v1/sync":{ "put":{ "tags":[ "Preferences" ], "operationId":"synchronizeUser", "summary":"Synchronize the preferences of the user", "description":"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.", "requestBody":{ "$ref":"#/components/requestBodies/SyncPreferences" }, "responses":{ "201":{ "description":"User preferences are synchronized.", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/PreferencesResponse" } }, "application/xml":{ "schema":{ "$ref":"#/components/schemas/PreferencesResponse" } }, "text/plain":{ "schema":{ "$ref":"#/components/schemas/PreferencesResponse" } } } }, "401":{ "description":"Unauthorized" }, "412":{ "description":"Invalid input", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/PrefAPIResponse" } }, "application/xml":{ "schema":{ "$ref":"#/components/schemas/PrefAPIResponse" } }, "text/plain":{ "schema":{ "$ref":"#/components/schemas/PrefAPIResponse" } } } }, "500":{ "description":"Internal server error" }, "503":{ "description":"Service Unavailable" } }, "security":[ { "context_auth":[ "write:context", "read:context" ] } ], "x-internal-id":"oaa-runtime-preferences-v1-sync-put", "x-filename-id":"oaa-runtime-preferences-v1-sync-put" } }, "/oaa/runtime/preferences/v1/fetchuserpreferencessecurely":{ "put":{ "tags":[ "Preferences" ], "operationId":"getUserPreferencesSecurely", "summary":"Returns user's challenge preferences as available in the OAA", "description":"Returns a list of challenge preferences for user. Error is returned for user not found in the OAA.

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.\n", "requestBody":{ "$ref":"#/components/requestBodies/PrefUserData" }, "responses":{ "200":{ "description":"Success.", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/UserPreferences" } }, "application/xml":{ "schema":{ "$ref":"#/components/schemas/UserPreferences" } } } }, "401":{ "description":"Unauthorized" }, "412":{ "description":"Invalid input", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/PrefAPIResponse" } }, "application/xml":{ "schema":{ "$ref":"#/components/schemas/PrefAPIResponse" } }, "text/plain":{ "schema":{ "$ref":"#/components/schemas/PrefAPIResponse" } } } }, "500":{ "description":"Internal server error" }, "503":{ "description":"Service Unavailable" } }, "security":[ { "context_auth":[ "write:context", "read:context" ] } ], "x-internal-id":"oaa-runtime-preferences-v1-fetchuserpreferencessecurely-put", "x-filename-id":"oaa-runtime-preferences-v1-fetchuserpreferencessecurely-put" } }, "/oaa/runtime/preferences/v1/truncateuserpreferencessecurely":{ "put":{ "tags":[ "Preferences" ], "operationId":"truncateUserPreferencesSecurely", "summary":"User Preferences are truncated.", "description":"Truncates user preferences. This API truncates user's preferences. It does not actually remove user from the OAA system.

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.", "requestBody":{ "$ref":"#/components/requestBodies/PrefTruncateRequest" }, "responses":{ "201":{ "description":"User preferences are truncated.", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/PrefAPIResponse" } }, "application/xml":{ "schema":{ "$ref":"#/components/schemas/PrefAPIResponse" } }, "text/plain":{ "schema":{ "$ref":"#/components/schemas/PrefAPIResponse" } } } }, "401":{ "description":"Unauthorized" }, "412":{ "description":"Invalid input", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/PrefAPIResponse" } }, "application/xml":{ "schema":{ "$ref":"#/components/schemas/PrefAPIResponse" } }, "text/plain":{ "schema":{ "$ref":"#/components/schemas/PrefAPIResponse" } } } }, "500":{ "description":"Internal server error" }, "503":{ "description":"Service Unavailable" } }, "security":[ { "context_auth":[ "write:context", "read:context" ] } ], "x-internal-id":"oaa-runtime-preferences-v1-truncateuserpreferencessecurely-put", "x-filename-id":"oaa-runtime-preferences-v1-truncateuserpreferencessecurely-put" } }, "/oaa-kba/runtime/kba/v1/questions":{ "get":{ "tags":[ "KBA" ], "summary":"Deprecated - Get questions of the user.", "description":"Since 12.2.1.4.1-20230630, this method is deprecated. See 'Get questions of the user securely' instead. \n\nQuestions that are associated with the user are returned. If user information is present, questions associated with the user is returned. These are questions preselected by the system to be used for KBA challenge.", "operationId":"getQuestions", "parameters":[ { "name":"userid", "in":"query", "description":"userid of user for whom questions will be fetched.", "required":false, "style":"form", "explode":true, "schema":{ "type":"string" } }, { "name":"group", "in":"query", "description":"group of user for whom questions will be fetched.", "required":false, "style":"form", "explode":true, "schema":{ "type":"string" } } ], "responses":{ "200":{ "description":"Success", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/QuestionsResponse" } }, "application/xml":{ "schema":{ "$ref":"#/components/schemas/QuestionsResponse" } } } }, "401":{ "description":"Unauthorized. User credentials invalid or not provided.", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/KBAAPIResponse" } } } }, "422":{ "description":"failed to get user questions for requested user.", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/KBAAPIResponse" } } } }, "500":{ "description":"Server error.", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/KBAAPIResponse" } } } } }, "x-internal-id":"oaa-kba-runtime-kba-v1-questions-get", "x-filename-id":"oaa-kba-runtime-kba-v1-questions-get" }, "put":{ "tags":[ "KBA" ], "summary":"Associate and update questions with answers specific to user.", "description":"The user is challenged with the active questions. Questions associated with users will be used during authentication to verify the user's identity. \n\nThe answers provided are stored as the user private answer for the question. The user identity data must be present in the body of the put request. The user associations as well as the user answers with the provided questions alone will be updated.\n\n Questions with Active flag set to true are considered active and may be used for challenging the user subsequently.\n\nThe user needs to activate at least one question per each choice of questions. The user may activate more than one question per choice based on the system property challenge.question.registration.maxcount.from.each.groups.\n\nBy default, the user may be challenged by any one of the active questions during authentication. Since 12.2.1.4.1-20230630, this behavior may be overridden by the system property oracle.security.oaa.kba.challenge.number if the system has been configured with adequate active questions.\n\nIf the OAA server is configured to challenge the user with multiple questions, the generated challenge will contain the multiple challenges as a string that contains the list of challenges separated by the value of the system property oracle.security.oaa.kba.challenge.separator.\n\nWhen the response to the challenge is presented to the OAA server, the response is also expected to be seperated by the same separator. By default, this separator is declared as '|' character. This may be overridden with any other character, or combination of characters that should not be used in the challenge or the response.", "operationId":"updateQuestions", "requestBody":{ "$ref":"#/components/requestBodies/UserQuestionData" }, "responses":{ "204":{ "description":"Success" }, "401":{ "description":"Unauthorized", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/KBAAPIResponse" } } } }, "415":{ "description":"Content-Type header value is invalid or not accepted on the server", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/KBAAPIResponse" } } } }, "422":{ "description":"Unprocessable Entity. Failed to update user question data.", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/KBAAPIResponse" } } } }, "500":{ "description":"Server error.", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/KBAAPIResponse" } } } } }, "x-internal-id":"oaa-kba-runtime-kba-v1-questions-put", "x-filename-id":"oaa-kba-runtime-kba-v1-questions-put" } }, "/oaa-kba/runtime/kba/v1/getquestionssecurely":{ "put":{ "tags":[ "KBA" ], "summary":"Get questions of the user securely.", "description":"Questions that are associated with the user are returned. If user information is present, questions associated with the user is returned. These are questions preselected by the system to be used for KBA challenge. ", "operationId":"getQuestionsSecurely", "requestBody":{ "$ref":"#/components/requestBodies/UserData" }, "responses":{ "200":{ "description":"Success", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/QuestionsResponse" } }, "application/xml":{ "schema":{ "$ref":"#/components/schemas/QuestionsResponse" } } } }, "401":{ "description":"Unauthorized. User credentials invalid or not provided.", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/KBAAPIResponse" } } } }, "422":{ "description":"failed to get user questions for requested user.", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/KBAAPIResponse" } } } }, "500":{ "description":"Server error.", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/KBAAPIResponse" } } } } }, "x-internal-id":"oaa-kba-runtime-kba-v1-getquestionssecurely-put", "x-filename-id":"oaa-kba-runtime-kba-v1-getquestionssecurely-put" } } }, "components":{ "schemas":{ "SecretKeyAPIResponse":{ "type":"object", "properties":{ "responseCode":{ "type":"string" }, "responseMessage":{ "type":"string" } } }, "SecretKey":{ "type":"object", "description":"A user's secret key.", "required":[ "secret_key" ], "properties":{ "secret_key":{ "description":"Secret key of user.", "type":"string" } } }, "CreateTotpConfigResponse":{ "type":"object", "description":"Details for creating a totp config for a user.", "required":[ "configUrl", "pin" ], "properties":{ "configUrl":{ "type":"string", "description":"The TOTP config URL" }, "deviceName":{ "type":"string", "description":"Name of the user's device" }, "pin":{ "type":"string", "description":"The TOTP config pin number" }, "expiryTimeInMs":{ "type":"integer", "format":"int64", "description":"The expiration time of the config URL and pin" } } }, "CreateSecretKeyRequest":{ "type":"object", "description":"Details for creating a secret key for a user. userName is mandatory parameter. API call should be made with canonical uniqueUserId along with userName and groupName. If userName and groupName is unique, the call can also be made using userName and groupName.", "required":[ "groupName", "userName" ], "properties":{ "groupName":{ "type":"string", "description":"User's group name." }, "userName":{ "type":"string", "description":"User's username." }, "deviceName":{ "type":"string", "description":"Name of the device. This should be recognizable by the user." }, "uniqueUserId":{ "type":"string", "description":"Canonical ID of the user. If this is present, then it takes precedence over userId + groupId combination." } } }, "CreateTotpConfigRequest":{ "type":"object", "description":"Details for creating a TOTP registration URL.", "required":[ "groupName", "userName" ], "properties":{ "groupName":{ "type":"string", "description":"User's group name." }, "userName":{ "type":"string", "description":"User's username." }, "deviceName":{ "type":"string", "description":"Name of the device. This should be recognizable by the user." }, "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." } } }, "ModelAPIResponse":{ "type":"object", "properties":{ "responseCode":{ "type":"string" }, "responseMessage":{ "type":"string" } } }, "ConfigAPIResponse":{ "required":[ "responseCode", "responseMessage" ], "type":"object", "properties":{ "responseCode":{ "type":"string" }, "responseMessage":{ "type":"string" } } }, "NameValPair":{ "required":[ "name", "value" ], "type":"object", "properties":{ "name":{ "type":"string", "description":"Property name." }, "value":{ "type":"string", "description":"Property Value String." } }, "description":"Name-value pair which can be used generically." }, "NameValSource":{ "required":[ "name", "source", "value" ], "type":"object", "properties":{ "name":{ "type":"string", "description":"Property name." }, "value":{ "type":"string", "description":"Property Value String." }, "source":{ "type":"string", "description":"Where is property loaded from. This can be file(product files of service implementation), environment(where service is running) or database(persistent store used by the service)." } }, "description":"Name-value and source of the property." }, "ConfigPropertiesRequest":{ "type":"array", "description":"The object is used to create or update Config Properties.", "items":{ "$ref":"#/components/schemas/NameValPair" } }, "ConfigPropertiesResponse":{ "type":"array", "description":"Contains Congfig Properties that are returned from API.", "items":{ "$ref":"#/components/schemas/NameValSource" } }, "AuthnRequest":{ "required":[ "clientInfo", "context" ], "type":"object", "properties":{ "userInfo":{ "$ref":"#/components/schemas/UserInfo" }, "clientInfo":{ "$ref":"#/components/schemas/ClientInfo" }, "context":{ "$ref":"#/components/schemas/UserContext" }, "timeToLiveInSec":{ "type":"integer", "description":"duration of the blocking call when initiating blocking call. After the duration, the blocking call will be invalidated. Default to 300 seconds (5 Mins)" } }, "description":"AuthnRequest contains user and context information to fetch challenges and initalize authn" }, "AuthnResponse":{ "type":"object", "properties":{ "correlationId":{ "type":"string", "description":"transaction id provided by the challenge api. Also this field contains previous id used within the session to update store." }, "resource":{ "type":"string", "description":"The resource for which the access was requested. This will be returned only when the user is authenticated and no further challenge is needed." }, "apiResponse":{ "$ref":"#/components/schemas/StatusInfo" }, "challengeselectiontext":{ "type":"string", "description":"Message to be displayed to select one of multiple challenges" }, "challengeInfo":{ "type":"array", "description":"A user can be challenged in many ways, the object will contain all the possible ways a user can be authenticated. In case the user information is not available in the request, the Default challenge mechanism as per the service provider configuration will be present.", "items":{ "$ref":"#/components/schemas/FactorChallengeInfo" } }, "nonce":{ "type":"string", "description":"random string to identify the future request. This will change in each response and the lastest nonce is expected in the finalize call." }, "challengecontext":{ "$ref":"#/components/schemas/InitContext" }, "cookies":{ "type":"array", "description":"Cookies present in the user access request.", "items":{ "$ref":"#/components/schemas/KeyValPair" } } }, "description":"The object describes the options available to end user for challenge otherwise also return the default challenge mechanism as per service provider." }, "UpdateAuthnRequest":{ "required":[ "challengeop", "correlationId" ], "type":"object", "properties":{ "correlationId":{ "type":"string", "description":"transaction id provided by the challenge api. Also this field contains previous id used within the session to update store." }, "nonce":{ "type":"string", "description":"random string to identify the future request. This will change in each response and the lastest nonce is expected in the finalize call." }, "challengedata":{ "$ref":"#/components/schemas/InitChallengeData" }, "challengeop":{ "type":"string", "description":"Requested operation to perform on the challenge API. It can be one of Init/Validate/Finalize. For init nonce is optional. Validate/Finalize nonce is required." }, "challengeAnswer":{ "type":"string", "description":"answer provided by the user to be passed to factor." }, "challengeResult":{ "type":"string", "description":"Result of the challenge. One of Success/Error/Failure. Validate will result in invocation of passive factor api to validate ChallengeAnswer. If the factor is not passive, exception will be thrown. Other result will be passed directly to finalize challenge call." }, "challengeResultReason":{ "type":"string", "description":"Reason for challenge result if it is failure. One of wrong_answer/too_many_attempts/channel_comm_error/other_error/unavailable_for_user/user_abandoned/user_timedout." } }, "description":"The object defines the request parametes for update authentication request." }, "UpdateAuthnResponse":{ "type":"object", "properties":{ "correlationId":{ "type":"string", "description":"transaction id provided by the challenge api. Also this field contains previous id used within the session to update store." }, "apiResponse":{ "$ref":"#/components/schemas/StatusInfo" }, "challengeselectiontext":{ "type":"string", "description":"Message to be displayed to select one of multiple challenges" }, "challengeInfo":{ "type":"array", "description":"A user can be challenged in many ways, the object will contain all the possible ways a user can be authenticated. In case the user information is not available in the request, the Default challenge mechanism as per the service provider configuration will be present.", "items":{ "$ref":"#/components/schemas/FactorChallengeInfo" } }, "nonce":{ "type":"string", "description":"random string to identify the future request. This will change in each response and the lastest nonce is expected in the finalize call." }, "challengecontext":{ "$ref":"#/components/schemas/InitContext" }, "cookies":{ "type":"array", "description":"Cookies present in the user access request.", "items":{ "$ref":"#/components/schemas/KeyValPair" } } }, "description":"The update response object." }, "AuthnAPIResponse":{ "type":"object", "properties":{ "responseCode":{ "type":"string" }, "responseMessage":{ "type":"string" } } }, "UserInfo":{ "required":[ "userId", "groups" ], "type":"object", "properties":{ "userId":{ "type":"string", "description":"The login id of user." }, "groups":{ "type":"array", "description":"The groups that user belongs to. OAA supports only one group element in array.", "items":{ "type":"string" } }, "uniqueUserId":{ "type":"string", "description":"Canonical ID of the user in the external systems. If this is present, then it takes precedence over userId + groupId combination." }, "locale":{ "type":"string", "description":"The current locale of the user which will override preferred locale in user preference." } }, "description":"User information provided by the caller to identify the user in the system. This is an optional parameter." }, "ClientInfo":{ "required":[ "clientId", "clientSecret" ], "type":"object", "properties":{ "ctype":{ "type":"string", "description":"Provides the information regarding the mechanism available for user interaction." }, "clientSecret":{ "type":"string", "description":"client secret that is used to validate the client" }, "clientId":{ "type":"string", "description":"Identifier of the client that uniquely identify the client" } }, "description":"Information about the calling service provider." }, "UserContext":{ "required":[ "customContext" ], "type":"object", "properties":{ "correlationId":{ "type":"string", "description":"transaction id provided by the challenge api if called previously." }, "assuranceLevel":{ "type":"object", "description":"requested assurance level by the end user. The field needs to be populated by service provider based on the requested resource." }, "customContext":{ "$ref":"#/components/schemas/CustomContext" } }, "description":"Additional context that can be provided by the caller while calling the preferecences API including assurance level, cookies, header, ip address, resource urls, user agents etc." }, "CustomContext":{ "required":[ "ipAddr" ], "type":"object", "properties":{ "userCookies":{ "type":"array", "description":"Cookies present in the user access request.", "items":{ "$ref":"#/components/schemas/KeyValPair" } }, "headers":{ "type":"array", "description":"Headers, if any, present in the user access request. The content will be provided as input for rule execution.", "items":{ "$ref":"#/components/schemas/KeyValPair" } }, "userAgent":{ "type":"string", "description":"user-agent string from the user request" }, "ipAddr":{ "type":"string", "description":"incoming ip address" }, "resource":{ "type":"string", "description":"Resource requested by the user." }, "ipforwarded":{ "type":"string", "description":"x-Forwarded-for from the user environment" }, "ldapgroup":{ "type":"array", "description":"ldap groups of the user", "items":{ "type":"string" } }, "ldapattributes":{ "type":"array", "description":"ldap atrributes of user", "items":{ "$ref":"#/components/schemas/KeyValPair" } }, "currentauthlevel":{ "type":"integer", "description":"current authentication level of the user, if any at the time of making the challenge request." }, "requestedauthlevel":{ "type":"integer", "description":"requested authn level of the user" } }, "description":"Additional context present in the user request." }, "KeyValPair":{ "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." }, "StatusInfo":{ "required":[ "status" ], "type":"object", "properties":{ "code":{ "type":"integer", "description":"Code representing the challenge status." }, "status":{ "type":"string", "description":"status of the fetch challenge info for user request. It will be one of the following authenticated/pending verification/pending identification/failed/error/missing registration/challenge blocked." }, "message":{ "type":"string", "description":"Error message generated if the server is unable to process the request." } }, "description":"Status of the fetch challenge info request. It contains the information required to process the user authentication request." }, "FactorChallengeInfo":{ "required":[ "displayOrder", "factorContext", "factorName", "factorUrl" ], "type":"object", "properties":{ "displayOrder":{ "type":"integer", "description":"The order of display to user when multiple factors are present" }, "factorUrl":{ "type":"string", "description":"URL of the factor" }, "factorName":{ "type":"string", "description":"name of the factor" }, "factorKey":{ "type":"string", "description":"key of the factor that can be used for registration." }, "factorContext":{ "$ref":"#/components/schemas/FactorContext" } }, "description":"information required to process user request using the factors available to it will be present in the object." }, "FactorContext":{ "required":[ "challengeAttrMap", "isSelected", "prompts" ], "type":"object", "properties":{ "promptselectmessage":{ "type":"string", "description":"Message to select one of the challenge prompts." }, "prompts":{ "type":"array", "description":"the display prompt will contain one or more prompts that can be further selected by user.", "items":{ "$ref":"#/components/schemas/Prompt" } }, "isSelected":{ "type":"boolean", "description":"if this is the selected option as per the user preference." }, "challengeAttrMap":{ "type":"array", "items":{ "$ref":"#/components/schemas/FactorAttribute" } } }, "description":"The context required by factor to process the user authentication request." }, "Prompt":{ "required":[ "promptmessage" ], "type":"object", "properties":{ "prompttext":{ "type":"string", "description":"Message string that can be displayed to end user for selection." }, "prompt":{ "type":"string", "description":"Masked device info." }, "challengeText":{ "type":"string", "description":"Message to be displayed on the challenge screen." }, "requiredInputType":{ "type":"string", "description":"Enumeration of none/text/radio/checkbox/textarea/waitingpage" }, "selected":{ "type":"boolean", "description":"if this particular prompt is selected." }, "name":{ "type":"string", "description":"friendly name of the device or the prompt." }, "verified":{ "type":"boolean", "description":"if the prompt is verified" }, "validated":{ "type":"boolean", "description":"if the prompt is validated" } }, "description":"Prompt the can be displayed to end user" }, "FactorAttribute":{ "type":"object", "properties":{ "factorAttributeName":{ "type":"string", "description":"Name of factor specific attribute." }, "factorAttributeValue":{ "type":"string", "description":"Value of factor specific attribute." }, "isVerified":{ "type":"boolean", "description":"is the given attribute is verified. Some attributes does not require verification hence this field is optional." }, "isValidated":{ "type":"boolean", "description":"If the given attribute is validated. Some attributes do not require validation hence this field is optional." } }, "description":"A map represented as an array of entries." }, "InitContext":{ "type":"object", "properties":{ "factorKey":{ "type":"string", "description":"the name of the factor that is selected by end user." }, "successURL":{ "type":"string", "description":"Resource where flow should be redirected to in case of successful challenge." }, "failureURL":{ "type":"string", "description":"Resource where flow should be redirected to in case of failed challenge. Most times this will be URL of the finalizerChallenge." }, "timeToLiveInSec":{ "type":"integer", "description":"duration of the blocking call when initiating blocking call. After the duration, the blocking call will be invalidated." }, "factorAttributes":{ "type":"array", "items":{ "$ref":"#/components/schemas/UserFactorAttribute" } }, "requestParams":{ "type":"array", "items":{ "$ref":"#/components/schemas/KeyValPair_2" } }, "userId":{ "type":"string", "description":"Identifier of the user. May be further qualified by groupId." }, "groupId":{ "type":"string", "description":"Group Id or app-name as applicable for user." }, "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." } } }, "UserFactorAttribute":{ "required":[ "userAttributeName", "userAttributeValue" ], "type":"object", "properties":{ "userAttributeName":{ "type":"string", "description":"Name of factor specific attribute for this user." }, "userAttributeValue":{ "type":"string", "description":"Value of factor specific attribute for this user." } }, "description":"A map represented as an array of entries." }, "KeyValPair_2":{ "required":[ "key", "value" ], "type":"object", "properties":{ "key":{ "type":"string", "description":"Key that can be used to fetch the related value." }, "value":{ "type":"object", "description":"Content that needs to be provided." } }, "description":"Key-value pair which can be used generically." }, "InitChallengeData":{ "required":[ "userId", "factorKey", "correlationId", "groupId" ], "type":"object", "properties":{ "userId":{ "type":"string", "description":"The login id of user. May be further qualified by groupId." }, "groupId":{ "type":"string", "description":"Group Id or app-name as applicable for user." }, "uniqueUserId":{ "type":"string", "description":"Canonical ID of the user in the external systems. If this is present, then it takes precedence over userId + groupId combination." }, "correlationId":{ "type":"string", "description":"Co-relation Id for this challenge. Factor implementation should use this in call back to SP/UAS during the finishChallenge call." }, "factorKey":{ "type":"string", "description":"the name of the factor that is selected by end user." }, "isRetry":{ "type":"boolean", "description":"If this is a retry." }, "successURL":{ "type":"string", "description":"Resource where flow should be redirected to in case of successful challenge." }, "failureURL":{ "type":"string", "description":"Resource where flow should be redirected to in case of failed challenge. Most times this will be URL of the finalizerChallenge." }, "timeToLiveInSec":{ "type":"integer", "description":"duration of the blocking call when initiating blocking call. After the duration, the blocking call will be invalidated." }, "abandonedChallenge":{ "type":"boolean", "description":"Flag to indicate if this challenge is abandoned by user." }, "factorAttributes":{ "type":"array", "items":{ "$ref":"#/components/schemas/UserFactorAttribute" } } }, "description":"Information about the user and user's registration for challenge factor." }, "PrefAPIResponse":{ "type":"object", "properties":{ "responseCode":{ "type":"string" }, "responseMessage":{ "type":"string" } } }, "DateTime":{ "type":"string", "format":"date-time", "description":"\"Date time string in the format rfc3339 sec 5.6. https://tools.ietf.org/html/rfc3339#section-5.6\"" }, "DateTimeRange":{ "type":"object", "example":"\"_, where is the start of time range, and is the end of the time range. '2019-12-31T10:10:00Z+07:00_to2019-12-31T10:11:00Z+07:00' represents 10 am to 11 am PDT on 31st December 2019.\"", "required":[ "from", "to" ], "properties":{ "from":{ "$ref":"#/components/schemas/DateTime" }, "to":{ "$ref":"#/components/schemas/DateTime" } } }, "UserPreferences":{ "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=.\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" } } } }, "FactorRegData":{ "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" } } } }, "PrefFactorAttributeValue":{ "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." } } }, "PrefFactorAttribute":{ "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." } } }, "PreferencesResponse":{ "type":"object", "properties":{ "preferences":{ "$ref":"#/components/schemas/UserPreferences" }, "message":{ "$ref":"#/components/schemas/PrefAPIResponse" } } }, "Pagination":{ "type":"object", "description":"Object determines pagination of results. Initial page is mandatory.", "properties":{ "pgInfo":{ "type":"string", "pattern":"(^\\d+(_d+){0-2}$|^$)", "description":"First integer is initial page. Second integer is number of pages. Third integer determines page size. Initial page is defaulted to 1 if not specified. Number of pages is defaulted to 10 if not specified. Page size is defaulted to 10 if not specified." } } }, "PrefTruncateRequest":{ "type":"object", "description":"Request object for truncating the preferences.", "required":[ "userId", "groupId" ], "properties":{ "userId":{ "description":"UserId or loginId of the user whose preferences data is to be deleted.", "type":"string" }, "groupId":{ "type":"string", "description":"GroupId / ApplicationId of the user whose preferences data is to be deleted. If this parameter is not present then, a value of Default is used." }, "uniqueUserId":{ "type":"string", "description":"Canonical ID of the user in the external systems. The call can be made using userId and groupId." }, "factorkey":{ "type":"string", "description":"factor key to be deleted in the user preference. This is optional field. If the field is missing then it all the factors in the user profile will be deleted." }, "devicename":{ "type":"string", "description":"Name of the device to be deleted in the user preference associated with factorkey. This is optional field and must also have factorykey if this parameter is provided." } } }, "SyncPreferences":{ "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" } } } }, "PrefUserData":{ "type":"object", "description":"Request Object contains userId and groupId.", "required":[ "userId", "groupId" ], "properties":{ "userId":{ "type":"string", "description":"Identifier of the user. May be further qualified by groupId." }, "groupId":{ "type":"string", "description":"Group to which user belongs.If this parameter is not present then, a value of Default is used.", "default":"Default" }, "uniqueUserId":{ "type":"string", "description":"Canonical ID of the user in the external systems. If this is present, then it takes precedence over userId + groupId combination." } } }, "KBAAPIResponse":{ "type":"object", "properties":{ "responseCode":{ "type":"string" }, "responseMessage":{ "type":"string" } } }, "User":{ "type":"object", "properties":{ "userid":{ "type":"string", "description":"userid unique in group." }, "group":{ "type":"string", "description":"group to which user belongs", "default":"default" }, "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." } } }, "Question":{ "required":[ "questionid" ], "type":"object", "properties":{ "questionId":{ "type":"integer", "description":"unique identifier of question associated with user", "format":"int64" }, "question":{ "type":"string", "description":"question text associated with user" }, "answer":{ "type":"string", "description":"User's answer to question associated with user" }, "active":{ "type":"boolean", "description":"If true, this question is associated with user and will be used to challenge the user.", "default":true } } }, "QuestionsResponse":{ "type":"object", "properties":{ "status":{ "type":"string", "description":"Status of the request" }, "message":{ "type":"string", "description":"Message related to the status of the request" }, "choices":{ "type":"array", "items":{ "$ref":"#/components/schemas/Choice" } } } }, "Choice":{ "type":"object", "properties":{ "questions":{ "type":"array", "items":{ "$ref":"#/components/schemas/Question" } } } }, "UserQuestion":{ "required":[ "categories" ], "type":"object", "properties":{ "user":{ "$ref":"#/components/schemas/User" }, "choices":{ "type":"array", "items":{ "$ref":"#/components/schemas/Choice" } } } } }, "requestBodies":{ "CreateSecretKeyRequest":{ "description":"Secret key request content.", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/CreateSecretKeyRequest" } }, "application/xml":{ "schema":{ "$ref":"#/components/schemas/CreateSecretKeyRequest" } } } }, "CreateTotpConfigRequest":{ "description":"TOTP config request content.", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/CreateTotpConfigRequest" } }, "application/xml":{ "schema":{ "$ref":"#/components/schemas/CreateTotpConfigRequest" } } } }, "ConfigPropertiesRequest":{ "description":"Input data for configuration property PUT API.", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/ConfigPropertiesRequest" } }, "application/xml":{ "schema":{ "$ref":"#/components/schemas/ConfigPropertiesRequest" } } } }, "AuthnRequest":{ "description":"User authentication request body", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/AuthnRequest" } }, "application/xml":{ "schema":{ "$ref":"#/components/schemas/AuthnRequest" } } } }, "UpdateAuthnRequest":{ "description":"User authentication update request", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/UpdateAuthnRequest" } }, "application/xml":{ "schema":{ "$ref":"#/components/schemas/UpdateAuthnRequest" } } } }, "UserPreferences":{ "description":"User Preferences contents", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/UserPreferences" } }, "application/xml":{ "schema":{ "$ref":"#/components/schemas/UserPreferences" } } } }, "SyncPreferences":{ "description":"User Preferences contents", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/SyncPreferences" } }, "application/xml":{ "schema":{ "$ref":"#/components/schemas/SyncPreferences" } } } }, "PrefUserData":{ "description":"Userdata contents", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/PrefUserData" } }, "application/xml":{ "schema":{ "$ref":"#/components/schemas/PrefUserData" } } } }, "PrefTruncateRequest":{ "description":"User Preferences content", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/PrefTruncateRequest" } }, "application/xml":{ "schema":{ "$ref":"#/components/schemas/PrefTruncateRequest" } } } }, "UserQuestionData":{ "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/UserQuestion" } }, "application/xml":{ "schema":{ "$ref":"#/components/schemas/UserQuestion" } } } }, "UserData":{ "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/User" } }, "application/xml":{ "schema":{ "$ref":"#/components/schemas/User" } } } } } } }