> ## 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.

# OTP Service Overview

> Secure one-time password generation and verification for authentication and user verification flows.

The Zeckta OTP Service enables applications to securely generate, deliver, and verify one-time passwords (OTPs) over SMS.

Common use cases include:

* User registration
* Login verification
* Multi-factor authentication (MFA)
* Password recovery
* Transaction authorization
* Device verification
* Email verification
* KYC verification

***

## How It Works

The OTP verification flow consists of two steps:

1. Request an OTP
2. Verify an OTP

```text theme={null}
Application
     ↓
Request OTP
     ↓
SMS Delivered
     ↓
User Receives Code
     ↓
Verify OTP
     ↓
Approved / Rejected
```

***

## Core Endpoints

| Action      | Method | Endpoint                    |
| ----------- | ------ | --------------------------- |
| Request OTP | `POST` | `/v1/messaging/otp/request` |
| Verify OTP  | `POST` | `/v1/messaging/otp/verify`  |

***

## OTP Lifecycle

```text theme={null}
REQUESTED
     ↓
APPROVED
```

Possible terminal outcomes:

```text theme={null}
INVALID
EXPIRED
ALREADY_USED
MAX_ATTEMPTS_REACHED
NOT_FOUND
```

***

## Session-Based Verification

Every OTP request generates a unique session identifier.

Example:

```json theme={null}
{
  "sessionId": "feab6011-2469-4804-ace5-ee9dcb5b9ef2",
  "expiresInSeconds": 300,
  "attemptsLeft": 5,
  "reused": false
}
```

The `sessionId` must be supplied when verifying an OTP.

***

## Security Features

<CardGroup cols={2}>
  <Card title="Expiration" icon="clock">
    OTPs automatically expire after a configured validity period.
  </Card>

  <Card title="Attempt Limits" icon="shield">
    Verification attempts are limited to reduce brute-force attacks.
  </Card>

  <Card title="Replay Protection" icon="lock">
    Successfully verified OTPs cannot be reused.
  </Card>

  <Card title="Workspace Isolation" icon="building">
    OTP sessions are isolated per workspace.
  </Card>
</CardGroup>

***

## Supported OTP Purposes

OTP requests must be associated with a business purpose.

Supported values:

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

These values help enforce business intent and prevent abuse.

***

## OTP Reuse

Zeckta can reuse an active OTP session when a valid OTP already exists for the same destination and purpose.

This helps reduce unnecessary SMS traffic and improves user experience.

When an existing OTP is reused:

```json theme={null}
{
  "sessionId": "feab6011-2469-4804-ace5-ee9dcb5b9ef2",
  "expiresInSeconds": 143,
  "attemptsLeft": 5,
  "reused": true
}
```

No additional SMS is sent.

<Info>
  When OTP reuse occurs, clients should continue using the existing session identifier and OTP code until the session expires.
</Info>

***

## OTP Expiration

OTPs remain valid for a limited period.

Default behavior:

```text theme={null}
TTL: 5 minutes
Maximum Attempts: 5
OTP Length: 6 digits
```

Applications should verify OTPs immediately after delivery.

***

## Verification Outcomes

Verification attempts can result in the following statuses:

| Status                 | Description                                 |
| ---------------------- | ------------------------------------------- |
| `APPROVED`             | OTP verified successfully.                  |
| `INVALID`              | Incorrect OTP code supplied.                |
| `EXPIRED`              | OTP validity period has elapsed.            |
| `ALREADY_USED`         | OTP has already been successfully verified. |
| `MAX_ATTEMPTS_REACHED` | Verification limit exceeded.                |
| `NOT_FOUND`            | OTP session does not exist.                 |

***

## 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.

***

## Security Best Practices

* Always use HTTPS when transmitting OTPs.
* Never expose API keys in client-side applications.
* Do not log OTP codes in plaintext.
* Verify OTPs immediately after delivery.
* Treat session identifiers as sensitive credentials.
* Expired or used OTPs should not be reused.

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Request OTP" href="/security-auth/send-token">
    Generate and deliver an OTP.
  </Card>

  <Card title="Verify OTP" href="/security-auth/verify-token">
    Verify an OTP using a session identifier.
  </Card>
</CardGroup>