OCS TOTP (Time-based One-time Password) Validation API

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

userid

string

The user id of the user to validate the TOTP for.

totp

string

The TOTP to validate.

Code Example

  • Curl

#!/usr/bin/env bash

USERNAME=admin
PASSWORD=password
API_PATH="ocs/v1.php/apps/twofactor_totp/api/v1/validate/<userid>/<totp>"
SERVER_URI="https://owncloud.install.com/owncloud"

curl "$SERVER_URI/$API_PATH/" \
    --user "$USERNAME:$PASSWORD"

Returns

The request returns either an XML (the default) or a JSON response, along with an HTTP 200 OK status code, which show whether:

  1. The TOTP is valid

  2. The TOTP is invalid

  3. 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:

  1. ocs/meta/status will be set to failure.

  2. ocs/meta/statuscode will be set to 404.

Example Responses

TOTP Is Valid

  • JSON

  • XML

{
    "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

  • JSON

  • XML

{
    "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

  • JSON

  • XML

{
    "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>