{
    "swagger":"2.0",
    "info":{
        "description":"The Oracle Access Manager Multifactor authentication OTP REST APIs enable one time pin generation and validation.",
        "version":"2019.09.06",
        "title":"REST API for Multifactor Authentication One Time PIN in Oracle Access Manager",
        "x-summary":"The Oracle Access Manager Multifactor authentication OTP REST APIs enable one time pin generation and validation."
    },
    "basePath":"/oam/services/rest/auth/api/v1/mfa",
    "schemes":[
        "http",
        "https"
    ],
    "consumes":[
        "application/json",
        "application/xml"
    ],
    "produces":[
        "application/json",
        "application/xml"
    ],
    "tags":[
        {
            "name":"OTP",
            "description":""
        }
    ],
    "paths":{
        "/createOTP":{
            "post":{
                "tags":[
                    "OTP"
                ],
                "summary":"Generates OTP",
                "description":"Generate OTP code for provided user, stores the OTP code for validation, and send using provided delivery channel. Must also be called before validating a TOTP code, in order to generate a valid correlationId. Configuration details can be found in OAM Admin Guide - Configuring the Adaptive Authentication Plug-in in the Oracle Access Management Console",
                "parameters":[
                    {
                        "name":"createOTPRequest",
                        "in":"body",
                        "description":"Create OTP request",
                        "required":true,
                        "schema":{
                            "$ref":"#/definitions/CreateOTPRequest"
                        }
                    }
                ],
                "responses":{
                    "200":{
                        "description":"Successful",
                        "schema":{
                            "$ref":"#/definitions/CreateOTPResponse"
                        }
                    },
                    "401":{
                        "description":"Unauthorized"
                    },
                    "404":{
                        "description":"Requested entity not found"
                    },
                    "422":{
                        "description":"Unprocessable Entity",
                        "schema":{
                            "$ref":"#/definitions/CreateOTPResponse"
                        }
                    },
                    "424":{
                        "description":"Failed Dependency",
                        "schema":{
                            "$ref":"#/definitions/CreateOTPResponse"
                        }
                    },
                    "500":{
                        "description":"Internal Server Error",
                        "schema":{
                            "$ref":"#/definitions/CreateOTPResponse"
                        }
                    }
                },
                "x-internal-id":"createOTP-post",
                "x-filename-id":"createotp-post"
            }
        },
        "/validateOTP":{
            "post":{
                "tags":[
                    "OTP"
                ],
                "summary":"Validate user provided OTP/TOTP code",
                "description":"Validates a user provided OTP/TOTP code against stored code generated by call to createOTP API. Configuration details can be found in OAM Admin Guide - Configuring the Adaptive Authentication Plug-in in the Oracle Access Management Console",
                "parameters":[
                    {
                        "name":"validateOTPRequest",
                        "in":"body",
                        "description":"Validate OTP request",
                        "required":true,
                        "schema":{
                            "$ref":"#/definitions/ValidateOTPRequest"
                        }
                    }
                ],
                "responses":{
                    "200":{
                        "description":"Successful",
                        "schema":{
                            "$ref":"#/definitions/ValidateOTPResponse"
                        }
                    },
                    "401":{
                        "description":"Unauthorized"
                    },
                    "404":{
                        "description":"Requested entity not found"
                    },
                    "422":{
                        "description":"Unprocessable Entity",
                        "schema":{
                            "$ref":"#/definitions/ValidateOTPResponse"
                        }
                    },
                    "424":{
                        "description":"Failed Dependency",
                        "schema":{
                            "$ref":"#/definitions/ValidateOTPResponse"
                        }
                    },
                    "500":{
                        "description":"Internal Server Error",
                        "schema":{
                            "$ref":"#/definitions/ValidateOTPResponse"
                        }
                    }
                },
                "x-internal-id":"validateOTP-post",
                "x-filename-id":"validateotp-post"
            }
        },
        "/challengeDisplayInfo":{
            "get":{
                "summary":"Challenge Display Information",
                "description":"Get display information for user attributes used in challenges.\n",
                "parameters":[
                    {
                        "name":"userId",
                        "type":"string",
                        "description":"User ID of user to get challenge display information for.",
                        "in":"query",
                        "required":true
                    },
                    {
                        "name":"appName",
                        "type":"string",
                        "description":"App name for application requesting challenge display information",
                        "in":"query",
                        "required":true
                    },
                    {
                        "name":"challengeType",
                        "type":"string",
                        "in":"query",
                        "description":"Types of challenge to return challenge display information for",
                        "required":false
                    },
                    {
                        "name":"idStore",
                        "type":"string",
                        "in":"query",
                        "description":"Identity Store Reference to find supplied user.",
                        "required":false
                    }
                ],
                "tags":[
                    "OTP"
                ],
                "responses":{
                    "200":{
                        "description":"Success",
                        "schema":{
                            "$ref":"#/definitions/ChallengeDisplayResponse"
                        }
                    },
                    "401":{
                        "description":"Unauthorized"
                    },
                    "404":{
                        "description":"Requested entity not found"
                    },
                    "422":{
                        "description":"Unprocessable Entity",
                        "schema":{
                            "$ref":"#/definitions/ChallengeDisplayResponse"
                        }
                    },
                    "500":{
                        "description":"Internal Server Error",
                        "schema":{
                            "$ref":"#/definitions/ChallengeDisplayResponse"
                        }
                    },
                    "default":{
                        "description":"Unexpected error",
                        "schema":{
                            "$ref":"#/definitions/ChallengeDisplayResponse"
                        }
                    }
                },
                "x-internal-id":"challengeDisplayInfo-get",
                "x-filename-id":"challengedisplayinfo-get"
            }
        }
    },
    "definitions":{
        "CreateOTPRequest":{
            "type":"object",
            "required":[
                "userId",
                "appName",
                "deliveryChannel"
            ],
            "properties":{
                "userId":{
                    "description":"Username of user to generate OTP code for.",
                    "type":"string"
                },
                "appName":{
                    "description":"Name defining calling app.",
                    "type":"string"
                },
                "deliveryChannel":{
                    "description":"Channel to deliver OTP to user. (sms|email|totp|custom)",
                    "type":"string"
                },
                "email":{
                    "description":"Email address of user to use for delivery of OTP code.",
                    "type":"string"
                },
                "phone":{
                    "description":"Phone number of user to use for delivery of OTP code.",
                    "type":"string"
                },
                "sessionId":{
                    "description":"SessionId associated with OTP generation.",
                    "type":"string"
                },
                "idStore":{
                    "description":"Identity Store Reference to find supplied user.",
                    "type":"string"
                }
            }
        },
        "CreateOTPResponse":{
            "properties":{
                "resultCode":{
                    "type":"string",
                    "description":"Response code indicating success (0) or error."
                },
                "correlationId":{
                    "type":"string",
                    "description":"Unique identifier for generated OTP code."
                },
                "minorCode":{
                    "type":"string",
                    "description":"Minor code indicating error or containing OTP code if delivery channel was \"custom\"."
                },
                "message":{
                    "type":"string",
                    "description":"Message describing error, if any."
                }
            }
        },
        "ValidateOTPRequest":{
            "type":"object",
            "required":[
                "userId",
                "correlationId",
                "otpCode",
                "appName"
            ],
            "properties":{
                "userId":{
                    "description":"Username of user to generate OTP code for.",
                    "type":"string"
                },
                "correlationId":{
                    "description":"CorrelationId returned by createOTP api.",
                    "type":"string"
                },
                "otpCode":{
                    "description":"User entered otp code to be validated.",
                    "type":"string"
                },
                "appName":{
                    "description":"Name defining calling app.",
                    "type":"string"
                },
                "sessionId":{
                    "description":"SessionId associated with OTP generation.",
                    "type":"string"
                },
                "deliveryChannel":{
                    "description":"Channel used for delivery of OTP. Only required if validating TOTP.",
                    "type":"string"
                },
                "idStore":{
                    "description":"Identity Store Reference to find supplied user.",
                    "type":"string"
                }
            }
        },
        "ValidateOTPResponse":{
            "properties":{
                "resultCode":{
                    "type":"string",
                    "description":"Response code indicating success (0) or error."
                },
                "minorCode":{
                    "type":"string",
                    "description":"Minor code indicating error details."
                },
                "message":{
                    "type":"string",
                    "description":"Message describing error, if any."
                }
            }
        },
        "ChallengeDisplayResponse":{
            "type":"object",
            "properties":{
                "resultCode":{
                    "type":"string",
                    "description":"Response code indicating success (0) or error."
                },
                "minorCode":{
                    "type":"string",
                    "description":"Minor code indicating error details."
                },
                "message":{
                    "type":"string",
                    "description":"Message describing error, if any."
                },
                "challengeInfoList":{
                    "description":"Array of challenge info objects.",
                    "type":"array",
                    "items":{
                        "$ref":"#/definitions/ChallengeInfo"
                    }
                }
            }
        },
        "ChallengeInfo":{
            "type":"object",
            "properties":{
                "challengeType":{
                    "type":"string",
                    "description":"Type of challenge associated with this piece of information (sms|email|totp|...)"
                },
                "prompt":{
                    "type":"string",
                    "description":"Display string for challenge information.  Eg. Masked email/phone number.  Masking based on configuration."
                },
                "contact":{
                    "type":"string",
                    "description":"Email/phone number associated with the challenge type."
                }
            }
        }
    }
}