# OTP API

### Overview

The Vudy OTP API allows third-party providers to generate temporary API keys for users through email-based one-time password authentication. This enables secure, time-limited access to Vudy's payment request creation endpoints.

### Authentication

All API requests require a valid API key in the `x-api-key` header. Contact Vudy support to obtain your API key.

```
x-api-key: your-api-key-here
```

{% hint style="warning" %}
Please make sure that your API key has the CREATE\_OTP Permission enabled for this to work correctly
{% endhint %}

### Endpoints

#### 1. Send OTP

**`POST https://vudy.tech/api/v1/user/send-otp`**

Sends a 9-character OTP code to the user's email address.

**Request Body:**

```json
{
    "email": "user@example.com"
}
```

**Response (Success):**

```json
{
    "success": true,
    "message": "OTP sent successfully",
    "code": "SOTP-005"
}
```

**Response (Error):**

```json
{
    "error": "User Not found",
    "code": "SOTP-002",
    "message": "Please create your account by going to https://vudy.me/login"
}
```

#### 2. Validate OTP

**`POST https://vudy.tech/api/v1/user/validate-otp`**

Validates the OTP code and returns a temporary API key.

**Request:**

```json
{
    "email": "user@example.com",
    "otp": "ABC123XYZ"
}
```

**Response (Success):**

```json
{
    "success": true,
    "message": "OTP validated successfully",
    "apiKey": "pk_uuid.userId",
    "expiresAt": "2024-01-01T12:15:00.000Z",
    "permissions": ["CREATE_REQUEST"]
}
```

**Response (Error):**

```json
{
    "error": "OTP expired or not found",
    "code": "VOTP-003",
    "message": "OTP has expired or was not found. Please request a new OTP."
}
```

### Usage Example

```javascript
// Step 1: Send OTP
const sendResponse = await fetch("https://vudy.tech/api/v1/user/send-otp", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "x-api-key": "your-api-key-here",
    },
    body: JSON.stringify({ email: "user@example.com" }),
});

// Step 2: User enters OTP from email
const userOtp = "ABC123XYZ"; // From user input

// Step 3: Validate OTP and get temporary API key
const validateResponse = await fetch(
    "https://vudy.tech/api/v1/user/validate-otp",
    {
        method: "POST",
        headers: {
            "Content-Type": "application/json",
            "x-api-key": "your-api-key-here",
        },
        body: JSON.stringify({
            email: "user@example.com",
            otp: userOtp,
        }),
    }
);

const { apiKey } = await validateResponse.json();

// Step 4: Use temporary API key for payment requests
const createRequest = await fetch("https://vudy.tech/api/v1/request/create", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "x-api-key": apiKey, // Use the temporary API key
    },
    body: JSON.stringify({
        amountInUsd: 25.0,
        note: "Service payment",
        generatedId: `order-${Date.now()}`,
    }),
});
```

### OTP Specifications

* **Format**: 9 characters (A-Z, 0-9)
* **Expiration**: 5 minutes
* **Single use**: OTP is invalidated after successful validation
* **Case sensitive**: OTPs should be entered exactly as received

### Temporary API Key

* **Expiration**: 15 minutes from creation
* **Permissions**: `CREATE_REQUEST` only
* **Rate limit**: 1 request per 5 seconds
* **Single user**: Tied to the validated user's account

### Error Codes

| Code       | Description                   |
| ---------- | ----------------------------- |
| `SOTP-001` | Invalid request data          |
| `SOTP-002` | User not found                |
| `SOTP-004` | Email delivery failed         |
| `SOTP-006` | Server error                  |
| `VOTP-001` | Invalid email/OTP combination |
| `VOTP-003` | OTP expired or not found      |
| `VOTP-004` | OTP doesn't match user        |
| `VOTP-005` | Server error                  |

### Requirements

* User must have a valid Vudy account
* User must have access to the provided email address
* Valid third-party API key for accessing endpoints

### Support

For API key requests or technical support, contact:

* **Email**: <support@vudy.me>
* **Documentation**: <https://docs.vudy.me>

### Rate Limits

* **OTP requests**: Contact support for rate limit information
* **Temporary API keys**: 1 request per 5 seconds per key