OCS TOTP (Time-based One-time Password) Validation API
Table of Contents
Introduction
The OCS TOTP (Time-based One-time Password) Validation API allows administrator users to validate if a TOTP is valid.
Only admin accounts can use this API. |
When 2FA (Two-Factor Authentication) is activated on an account, authorization with a username and password is not possible. Requests must authenticate via app passwords. |
Prerequisites
This API requires the 2-Factor Authentication app to be installed and enabled.
Validate TOTP
-
Path:
ocs/v1.php/apps/twofactor_totp/api/v1/validate/<userid>/<totp>
-
Method:
GET
Request Parameters
Attribute | Type | Description |
---|---|---|
|
string |
The user id of the user to validate the TOTP for. |
|
string |
The TOTP to validate. |
Returns
The request returns either an XML (the default) or a JSON response, along with an HTTP 200 OK
status code, which show whether:
-
The TOTP is valid
-
The TOTP is invalid
-
The user was not found
The status of the TOTP is located in the ocs/data/result
element.
If the user was not found, then:
-
ocs/meta/status
will be set tofailure
. -
ocs/meta/statuscode
will be set to404
.
Example Responses
TOTP Is Valid
{
"ocs": {
"meta": {
"status": "ok",
"statuscode": 100,
"message": "OK",
"totalitems": "",
"itemsperpage": ""
},
"data": {
"result": true
}
}
}
<?xml version="1.0"?>
<ocs>
<meta>
<status>ok</status>
<statuscode>100</statuscode>
<message>OK</message>
<totalitems></totalitems>
<itemsperpage></itemsperpage>
</meta>
<data>
<result>1</result>
</data>
</ocs>
TOTP Is Not Valid
{
"ocs": {
"meta": {
"status": "ok",
"statuscode": 100,
"message": "OK",
"totalitems": "",
"itemsperpage": ""
},
"data": {
"result": false
}
}
}
<?xml version="1.0"?>
<ocs>
<meta>
<status>ok</status>
<statuscode>100</statuscode>
<message>OK</message>
<totalitems></totalitems>
<itemsperpage></itemsperpage>
</meta>
<data>
<result></result>
</data>
</ocs>
User or Secret Not Found
{
"ocs": {
"meta": {
"status": "failure",
"statuscode": 404,
"message": "OK",
"totalitems": "",
"itemsperpage": ""
},
"data": {
"result": false
}
}
}
<?xml version="1.0"?>
<ocs>
<meta>
<status>failure</status>
<statuscode>404</statuscode>
<message>OK</message>
<totalitems></totalitems>
<itemsperpage></itemsperpage>
</meta>
<data>
<result></result>
</data>
</ocs>