---
title: "OTP Auth Request"
method: POST
path: "/otp/auth"
tags: ["OTP"]
---

# OTP Auth Request

`POST /otp/auth`

## Request

- Base URL: `https://api.commpeak.com/textpeak/streams`
- URL: `https://api.commpeak.com/textpeak/streams/otp/auth`
- Auth: API key in header `Authorization`

Send a one-time password (OTP) to a recipient. TextPeak generates the code, delivers it using your OTP settings, and returns a `request_uuid`.

**Channels and fallback.** Your OTP settings list the channels to try in order (SMS, WhatsApp Business, voice, Telegram). When a channel fails to deliver, the next one is tried automatically. `provider` pins one channel for a single attempt instead.

**Resending.** While a code is active, a second request for the same recipient returns `409`. Send `retry: true` to resend on the next channel — the `request_uuid` stays the same. When no channels are left, `retry` returns `409` too.

**Your end user's IP.** Pass `client_ip` when you call from your backend, so the per-IP limit applies to your user rather than to your server.

**Configured in your OTP settings** (not request fields): code length (default 5 digits), how long a code stays valid (default 300 seconds), how many codes a recipient may request (default 10) and from one IP, how many wrong codes are allowed (default 5), and the cool-down that resets those counters (default 1800 seconds).

**Errors.** `401` invalid token · `402` balance depleted · `403` blocked · `409` code already active, or nothing left to retry · `422` invalid phone number or `provider` · `429` too many requests for this recipient or IP. Errors use the standard error envelope.

**Authentication:** OTP token (the stream token of an OTP stream) in the `Authorization` header (see **Authentication** in the API Overview).

## Request body

- SendOTPRequest
  - `recipient_phone` string, required: The phone number to send the code to, in international format.
  - `client_ip` string, nullable: Your end user's IP address. Used for the per-IP request limit. Defaults to the IP address of the server calling the API, so set it when you call from a backend.
  - `retry` boolean, nullable: Resend while a code is still active: the code goes out again on the next channel of your OTP settings, under the same `request_uuid`. Without `retry`, a second request for the same recipient returns `409`.
  - `provider` 'sms' | 'whatsapp_business' | 'voice', nullable: Send on this one channel instead of the configured channel order. It must be one of your configured channels. A pinned request is a single attempt: no fallback to other channels, and it cannot be retried.
  - `event` string, nullable: Message template for the code, by its `eventKey`. Defaults to the template in your OTP settings.
  - `template_variables` object, nullable: Extra template values. When your OTP settings say you generate codes yourself, `template_variables.code` is the code to send and is required.

## Response `200`

Successful Response

- SendOTPResponse
  - `status` boolean, required: `true` when the code was accepted for sending.
  - `request_uuid` string, required: Identifier of this OTP request. Stays the same across retries.
  - `code` string, nullable: The code that was sent. Returned only when your OTP settings expose it.

## Other responses

- `401`: Invalid token, or the token is not valid from this IP address.
- `402`: Payment required: the account balance is depleted (`0x41`).
- `403`: Missing token, blocked IP address, or the stream is not available (`0x11`, `0x16`, `0x21`, `0x22`).
- `409`: Conflict with a request already in progress (see the endpoint description).
- `422`: Invalid phone number or `provider`, or a required `template_variables.code` is missing.
- `429`: Rate limit reached (see the endpoint description).

---

[API](https://skmtc.dev/commpeak/apis/commpeak-textpeak-streams-api.md) - [All operations](https://skmtc.dev/commpeak/apis/commpeak-textpeak-streams-api/llms.txt) - [OpenAPI document](https://skmtc.dev/commpeak/apis/commpeak-textpeak-streams-api/revisions/b9aaa8b4efa2?raw)