> ## Documentation Index
> Fetch the complete documentation index at: https://developer.zeckta.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Request OTP

> Generate and deliver a one-time password (OTP) via SMS.

Use this endpoint to generate and deliver a one-time password (OTP) to a recipient.

The response contains a session identifier that must be supplied when verifying the OTP.

***

## Endpoint

```http theme={null}
POST /v1/messaging/otp/request
```

***

## Authentication

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

***

## Request Body

| Field             | Type   | Required | Description                                       |
| ----------------- | ------ | -------- | ------------------------------------------------- |
| `dest`            | string | Yes      | Recipient phone number in international format.   |
| `src`             | string | Yes      | Sender Name used to deliver the OTP.              |
| `purpose`         | string | Yes      | Business purpose associated with the OTP request. |
| `messageTemplate` | string | No       | Custom SMS template used for OTP delivery.        |

***

## Supported Purposes

```text theme={null}
LOGIN
PASSWORD_RESET
TRANSACTION
DEVICE_VERIFICATION
EMAIL_VERIFICATION
ACCOUNT_RECOVERY
KYC_VERIFICATION
```

***

## Example Request

```json theme={null}
{
  "dest": "+233202007745",
  "src": "ZECKTA",
  "purpose": "LOGIN"
}
```

***

## Successful Response

```json theme={null}
{
  "success": true,
  "message": "OTP sent successfully",
  "data": {
    "sessionId": "feab6011-2469-4804-ace5-ee9dcb5b9ef2",
    "expiresInSeconds": 300,
    "attemptsLeft": 5,
    "reused": false
  }
}
```

***

## Response Fields

| Field              | Description                                           |
| ------------------ | ----------------------------------------------------- |
| `sessionId`        | Unique OTP session identifier.                        |
| `expiresInSeconds` | Remaining OTP validity period in seconds.             |
| `attemptsLeft`     | Remaining verification attempts available.            |
| `reused`           | Indicates whether an existing OTP session was reused. |

***

## OTP Reuse

When OTP reuse is enabled, Zeckta may reuse an active OTP session if a valid OTP already exists for the same destination and purpose.

In this scenario:

* No new OTP is generated
* No additional SMS is sent
* The existing OTP remains valid until expiration

Example:

```json theme={null}
{
  "success": true,
  "message": "Active OTP already exists. No new SMS sent.",
  "data": {
    "sessionId": "feab6011-2469-4804-ace5-ee9dcb5b9ef2",
    "expiresInSeconds": 143,
    "attemptsLeft": 5,
    "reused": true
  }
}
```

<Info>
  When `reused` is `true`, clients should continue using the existing OTP and session identifier.
</Info>

***

## Validation Rules

### Destination Number

Must be supplied in international E.164 format.

Example:

```text theme={null}
+233202007745
```

### Sender Name

Must be a valid Sender Name available to your workspace.

Example:

```text theme={null}
ZECKTA
```

### Message Template

Optional custom message template.

If omitted, Zeckta uses the default OTP template.

***

## Default Configuration

```text theme={null}
Validity Period: 5 Minutes
Maximum Verification Attempts: 5
OTP Length: 6 Digits
```

***

## Workspace Isolation

OTP sessions are isolated by workspace.

A workspace can only:

* Request OTPs using its own API key
* Verify OTPs generated within its own workspace
* Access sessions associated with its own credentials

Cross-workspace access is not permitted.

***

## Next Step

<Card title="Verify OTP" href="/security-auth/verify-token" icon="check">
  Validate a received OTP using the session identifier returned from this endpoint.
</Card>