# Time based Authentication

{% hint style="info" %}
**API calls are region specific. Please make sure you are subscribed to a specific region and have a valid Renda API Key before making API calls.**

Region Specific URLs:\
\
Ireland(Europe): \*\*<https://api-eu.renda.io**\\>
North Virginia(US): \*\*<https://api-us.renda.io**\\>
Mumbai(APAC): **<https://api-apac.renda.io>**
{% endhint %}

## Get Ping

<mark style="color:blue;">`GET`</mark> `https://api-<region>.renda.io/totp/ping`

Region specific URLs:\
Ireland(Europe):**`https://api-eu.renda.io/totp/ping`**\
North Virginia(US): **`https://api-us.renda.io/totp/ping`**\
Mumbai(APAC): **`https://api-apac.renda.io/totp/ping`**

#### Headers

| Name      | Type   | Description   |
| --------- | ------ | ------------- |
| x-api-key | string | Renda API Key |

{% tabs %}
{% tab title="200 Ping successful" %}

```
    {
        "type": "Success",
        "message": "Renda.io ping successful"
    }
]
```

{% endtab %}

{% tab title="403 Invalid API Key " %}

```
{
    "message”:”Please check the following: 1) An *active* Renda.io 
    subscription 2) API being invoked must be *Subscribed* in Renda 
    developer portal 3) A valid *API Key* must be passed in ‘x-api-key’ 
    request header parameter. Please refer to Renda documentation for 
    more details - https://documentation.renda.io"
}
```

{% endtab %}
{% endtabs %}

## generateQRCode

<mark style="color:green;">`POST`</mark> `https://api-<region>.renda.io/totp/generateQRCode`

Generate QR Code API encodes any form data such as text, URL, phone numbers etc., into a QR code.

#### Headers

| Name         | Type   | Description                       |
| ------------ | ------ | --------------------------------- |
| x-api-key    | string | Renda API Key                     |
| Accept       | string | \*/\*                             |
| Content-type | string | application/x-www-form-urlencoded |

#### Request Body

| Name | Type   | Description                       |
| ---- | ------ | --------------------------------- |
| data | string | Data to be encoded in the QR Code |

{% tabs %}
{% tab title="200 QR code in png format" %}

```
<QR Code in png format>
```

{% endtab %}

{% tab title="400 " %}

```
[
    {
        "type": "Error",
        "message": "No Data provided to generate QR Code"
    }
]
```

{% endtab %}

{% tab title="403 Invalid API Request" %}

```
{
    "message": "Unsupported API request. Please refer to Renda 
    documentation for more details documentation.renda.io"
}
```

{% endtab %}
{% endtabs %}

## onboardUser

<mark style="color:green;">`POST`</mark> `https://api-<region>/renda.io/totp/onboardUser`

Onboard user API generates a secret key based on userid(which can be email address, name, number etc.,) and application ID. This API is useful to build user onboarding/authentication module whereby users can be authenticated using **time based one time password (TOTP) generated by any soft token generator.** \
\
This API returns a secret key, OTP URL, QR Code image encoded with the OTP URL which can be scanned to setup any soft key generator and a current TOTP passcode

#### Headers

| Name         | Type   | Description                       |
| ------------ | ------ | --------------------------------- |
| x-api-key    | string | Renda API Key                     |
| Content-Type | string | application/x-www-form-urlencoded |

#### Request Body

| Name          | Type   | Description                                 |
| ------------- | ------ | ------------------------------------------- |
| userID        | string | User ID (Email address, Employee ID etc.,)  |
| applicationID | string | Application ID (Name of the app)            |
| tokenValidity | string | Token refresh interval - Default is 30 secs |
| tokenLength   | string | Token Length - Default is 6 digits          |

{% tabs %}
{% tab title="200 " %}

```
{
    "secretKey": "LVJFKZI5AJZXIZKG",
    "otpURL": "otpauth://totp/Renda:jafferali?secret=LVJFKZI5AJZXIZKG&period=30&digits=6&algorithm=SHA1&issuer=Renda",
    "QRCode": "data:image/png;base64,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",
    "token": "605250"
}
```

{% endtab %}

{% tab title="400 Parameters missing" %}

```
[
    {
        "type": "Error",
        "message": "User ID is mandatory"
    },
    {
        "type": "Error",
        "message": "Application ID is mandatory"
    }
]
```

{% endtab %}
{% endtabs %}

## getOTP

<mark style="color:green;">`POST`</mark> `https://api-<region>.renda.io/totp/getOTP`

This API fetches the current valid OTP for a specified secret key. Token validity and token length parameters can be passed if they customised to be more than 30 seconds in duration and 6 digits in length

#### Headers

| Name         | Type   | Description                       |
| ------------ | ------ | --------------------------------- |
| x-api-key    | string | Renda API Key                     |
| Content-Type | string | application/x-www-form-urlencoded |

#### Request Body

| Name          | Type   | Description                         |
| ------------- | ------ | ----------------------------------- |
| secret        | string | Secret Key                          |
| tokenValidity | string | Token validity (default to 30 secs) |
| tokenLength   | string | Token length (defaults to 6 digits) |

{% tabs %}
{% tab title="200 " %}

```
{
    "currentToken": "667122",
    "timeUsed": 10,
    "timeRemaining": 20,
    "previousToken": "008989",
    "nextToken": "390535"
}
```

{% endtab %}

{% tab title="400 Bad request" %}

```
[
    {
        "type": "Error",
        "message": "secret cannot be empty"
    }
]
```

{% endtab %}

{% tab title="403 " %}

```
{
    "message": "Unsupported API request. Please refer to Renda 
    documentation for more details documentation.renda.io"
}
```

{% endtab %}
{% endtabs %}

## verifyOTP

<mark style="color:green;">`POST`</mark> `https://api-<region>.renda.io/totp/verifyOTP`

This API method verifies the provided one time password(OTP) against a specific Secret key. Token validity can be passed in the validity period needs to be extended beyond the default 30 seconds.

#### Headers

| Name         | Type   | Description                       |
| ------------ | ------ | --------------------------------- |
| x-api-key    | string | Renda API key                     |
| Content-Type | string | application/x-www-form-urlencoded |

#### Request Body

| Name          | Type   | Description                         |
| ------------- | ------ | ----------------------------------- |
| secret        | string | Secret Key                          |
| token         | string | OTP Token                           |
| tokenValidity | string | Token validity (Default 30 seconds) |

{% tabs %}
{% tab title="200 " %}

```
{
    "isValid": false,
    "token": "911726",
    "timeUsed": 27,
    "timeRemaining": 3
}
```

{% endtab %}

{% tab title="400 Mandatory parameters missing" %}

```
[
    {
        "type": "Error",
        "message": "Token cannot be empty"
    },
    {
        "type": "Error",
        "message": "Secret cannot be empty"
    }
]
```

{% endtab %}

{% tab title="403 Invalid API Call" %}

```
{
    "message": "Unsupported API request. Please refer to Renda 
    documentation for more details documentation.renda.io"
}
```

{% endtab %}
{% endtabs %}