# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://documentation.renda.io/microservices/time-based-authentication.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.