OAA Runtime API

Create Registration URL

post

/oaa/runtime/totp/registrationurl/v1/

Use this API to generate a TOTP registration URL.

Request

There are no request parameters for this operation.

Supported Media Types

application/xml
application/json

Root Schema : schema

Type: object

Details for creating a TOTP registration URL.

Show Source

deviceName: string

Name of the device. This should be recognizable by the user.
groupName(required): string

User's group name.
uniqueUserId: string

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

User's username.

{
    "required":[
        "groupName",
        "userName"
    ],
    "type":"object",
    "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."
        }
    },
    "description":"Details for creating a TOTP registration URL."
}

Root Schema : schema

Type: object

Details for creating a TOTP registration URL.

Show Source

deviceName: string

Name of the device. This should be recognizable by the user.
groupName(required): string

User's group name.
uniqueUserId: string

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

User's username.

{
    "required":[
        "groupName",
        "userName"
    ],
    "type":"object",
    "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."
        }
    },
    "description":"Details for creating a TOTP registration URL."
}

Response

Supported Media Types

application/xml
application/json
text/plain

201 Response

Registration URL has been created.

Root Schema : CreateTotpConfigResponse

Type: object

Details for creating a totp config for a user.

Show Source

configUrl(required): string

The TOTP config URL
deviceName: string

Name of the user's device
expiryTimeInMs: integer (int64)

The expiration time of the config URL and pin
pin(required): string

The TOTP config pin number

{
    "required":[
        "configUrl",
        "pin"
    ],
    "type":"object",
    "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",
            "description":"The expiration time of the config URL and pin",
            "format":"int64"
        }
    },
    "description":"Details for creating a totp config for a user."
}

400 Response

Bad Request

401 Response

Unauthorized

403 Response

Could not create TOTP config

422 Response

Requested user information not found

500 Response

Internal server error

503 Response

Service Unavailable

Examples

The following example shows a sample request and response for generating a Time-based One Time Password (TOTP) registration URL.

cURL Command to Generate a TOTP Registration URL in JSON Format

curl --location --request POST '<OAAService>/oaa/runtime/totp/registrationurl/v1' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic <Base64Encoded(<username>:<password>)>' \
--data '{
"userName": "testuser4",
"groupName": "financeapp4",
"deviceName": "JoeSmithDevice3"
}'

Sample Response in JSON Format

configUrl": "oraclemobileauthenticator://settings?ServiceName::=JoeSmithDevice3&ServiceType::=SharedSecret&SharedSecretAuthServerType::=HTTPBasicAuthentication&LoginURL::=https://oaa.example.com:12345/oaa/rui/totpPreferences/v1?contextInfo=dGVzdHVzZXI0OmZpbmFuY2VhcHA0OjJjYmM5ZDczLWIyZDItNGI0ZC05YjZkLTkxNjFiMDkwYjg3NjpSYW5qYW5EZXZpY2Uz",
"deviceName": "JoeSmithDevice3",
"pin": "NTUzNDgy",
"expiryTimeInMs": 1696327720855
}

cURL Command to Generate a TOTP Registration URL in XML Format

curl --location --request POST '<OAAService>/oaa/runtime/totp/registrationurl/v1' \
--header 'Content-Type: application/xml' \
--header 'Accept: application/xml' \
--header 'Authorization: Basic <Base64Encoded(<username>:<password>)>' \
--data '<?xml version="1.0" encoding="UTF-8" ?>
<CreateTotpConfigRequest>
	<userName>testuser4</userName>
	<groupName>financeapp4</groupName>
	<deviceName>JoeSmithDevice3</deviceName>
</CreateTotpConfigRequest>'

Sample Response in XML Format

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<CreateTotpConfigResponse>
	<configUrl>oraclemobileauthenticator://settings?ServiceName::=JoeSmithDevice3&ServiceType::=SharedSecret&SharedSecretAuthServerType::=HTTPBasicAuthentication&LoginURL::=https://oaa.example.com:12345/oaa/rui/totpPreferences/v1?contextInfo=dGVzdHVzZXI0OmZpbmFuY2VhcHA0OmY2ODI5N2M2LTY4ZDgtNDU5OC05NDc1LTAxNWRmZWExNTM2MzpSYW5qYW5EZXZpY2Uz</configUrl>
	<deviceName>JoeSmithDevice3</deviceName>
	<pin>ODE4ODM2</pin>
	<expiryTimeInMs>1696328061642</expiryTimeInMs>
</CreateTotpConfigResponse>