Karibu OTP API - Karibu Docs

A complete reference for integrating Briq’s One-Time Password (OTP) API. The API lets you generate, deliver, verify, resend, and invalidate short numeric codes over SMS, voice call, or WhatsApp, scoped to the Developer App bound to your X-API-Key.

API surface: https://karibu.briq.tz/v1/otp/*
Audience: backend engineers integrating phone-based verification (signup, login, transaction confirmation).
Version: v1.2

1. Overview

The Karibu OTP API is a stateless HTTP service that:

Generates a numeric OTP (default 6 digits) and delivers it to a phone number via SMS (default), voice call, or WhatsApp.
Verifies a code submitted by the end user, with a hard cap of 3 attempts per active OTP.
Manages lifecycle: resend, invalidate, and inspect the currently active OTP for a (phone, app) pair.

Codes are stored hashed (bcrypt) — the server never returns the plaintext code in any response. Only the recipient sees it via the SMS, call, or WhatsApp message.

Channel comparison

Channel	`delivery_method`	Best for	Customisable per-call?
SMS	`"sms"`	Default; broadest reach	`sender_id`, `message_template`
Voice call	`"call"`	SMS-restricted regions, accessibility	none — TTS reads the code
WhatsApp	`"whatsapp"`	App-installed users, rich-format follow-ups	none — uses the platform-approved `briq_otp` template

2. Prerequisites

Before integrating, make sure you have:

A Briq account with a workspace.
An active developer API key (X-API-Key) bound to a Developer App. Generate one in the Briq dashboard and attach it to the app that scopes your OTP traffic.
At least one Developer App registered against your workspace (required for binding). Each app gives you an app_id (UUID) returned in API responses for reference.
The workspace must allow developer access (toggle in workspace settings).
Recipient phone numbers in E.164 digits-only format (no +, no spaces, e.g. 255712345678).

Bind every OTP API key to a Developer App and keep it server-side. If you don’t yet have a Developer App, see Developer Apps before continuing.Legacy integrations with an unbound API key may scope requests via the optional X-App-ID header or an app_key field in the body or query. New integrations should bind the key instead.

3. Authentication & host

Base URL

https://karibu.briq.tz

All OTP endpoints are versioned under /v1/otp/.

Required headers

Header	Required	Notes
`X-API-Key`	yes	Your developer API key, bound to a Developer App. Must be active and not expired.
`X-App-ID`	no	Optional Developer App UUID. When sent, must match the app bound to your API key — otherwise 403. Omit when the key is bound.
`Content-Type`	yes (POST)	`application/json`
`Host`	yes	Must be `karibu.briq.tz` (or `docs.briq.tz`). Other hosts are rejected with 403 outside `development`/`sandbox` envs.

App scoping

Karibu resolves your Developer App from the bound X-API-Key on every OTP endpoint:

Your API key must be bound to a Developer App you own.
The Developer App’s workspace must allow developer access for your user — otherwise 403 (Workspace does not allow developer access.).
If you send optional X-App-ID, it must match the app bound to your API key — otherwise 403.

These checks run on every endpoint described below.

4. Standard response envelope

Every endpoint returns the same JSON envelope:

{
  "success": true,
  "message": "Human-readable summary",
  "data": { /* endpoint-specific payload, or null */ },
  "status_code": 200
}

success — true for normal operation, false for handled errors / “not found” cases embedded in the envelope.
message — short human-readable string suitable for logging.
data — endpoint-specific. May be null.
status_code — mirrors the HTTP status code returned.

Errors raised by FastAPI itself (401, 403 from auth/host gates, 422 from validation) follow the standard {"detail": "..."} shape, not the envelope above.

5. Behavioral rules (read this first)

These rules apply across all endpoints. Designing your client around them upfront prevents most integration bugs.

Rule	Detail
Single active OTP per `(phone, app)`	`request` and `resend` invalidate any prior unused, unexpired OTP for the same phone scoped to the same Developer App before issuing a new one.
Hashed at rest	OTP codes are bcrypt-hashed. The plaintext is delivered only via SMS, call, or WhatsApp to the recipient. The server will never return it in any response.
3-attempt cap on `verify`	After 3 wrong codes the OTP is auto-locked (marked used) and `remaining_attempts` becomes `0`. The user must request a new OTP.
Default expiry	10 minutes. Configure per call via `minutes_to_expire`.
Default OTP length	6 digits. Configure per call via `otp_length`.
Delivery method	`"sms"` (default), `"call"`, or `"whatsapp"`. Anything else returns 400.
Sender ID	SMS only. Defaults to the platform-configured `OTP_DEFAULT_SENDER_ID` if omitted. Ignored on `"call"` and `"whatsapp"`.
Message template	SMS only. Optional. Must include `{code}`. `{expiry}` is also substituted. If `{code}` is missing the server falls back to the default template. Ignored on `"call"` and `"whatsapp"`.
WhatsApp sender resolution	WhatsApp only. The dispatcher resolves which sender number to dispatch from in this order: (1) a non-default WhatsApp sender owned by your developer user with an APPROVED `briq_otp` template; (2) the sender whose Infobip `phone_number_id` matches the platform-wide `WHATSAPP_PHONE_NUMBER_ID` env value; (3) the legacy `is_default = TRUE` sender row. You don’t pass any sender field — the resolution is automatic.
Phone format	E.164 digits only, no `+`. e.g. `255712345678`. Invalid input → 400 `"Invalid phone number"`.
Cross-app isolation	Status, verify, resend, and invalidate operate only on OTPs issued under the same Developer App (resolved from your bound API key). An OTP issued under app A cannot be verified, queried, or invalidated via app B.

6. Endpoint reference

Each endpoint section below documents purpose, contract, error semantics, and copy-pasteable client snippets in cURL, Python (requests), Node.js (fetch), and PHP (cURL extension).

6.1 `POST /v1/otp/request`

Generate a fresh OTP and deliver it to the phone. Method & path: POST https://karibu.briq.tz/v1/otp/request Headers: X-API-Key (bound to a Developer App), Content-Type: application/json. Common fields (every channel):

Field	Type	Required	Default	Notes
`phone_number`	string (E.164 digits)	yes	—	e.g. `255712345678`
`app_key`	string	no	—	Omit when API key is bound to a developer app. Legacy unbound keys may send this or use `X-App-ID` instead.
`delivery_method`	string	yes (recommended)	`"sms"`	one of `"sms"`, `"call"`, `"whatsapp"`
`otp_length`	int	no	`6`	code length
`minutes_to_expire`	int	no	`10`	TTL
`callback_url`	string (HTTPS)	no	—	Optional per-request webhook for async `flake.verified` / `flake.failed` events. Active for this OTP’s lifetime.
`callback_secret`	string	no	—	Optional HMAC secret for `X-Briq-Signature` on callbacks.

The remaining fields are channel-specific. Pick the tab below that matches the channel you’re sending on — each one shows the exact payload, the success response shape, and copy-pasteable client snippets. Success response (same shape across channels):

{
  "success": true,
  "message": "OTP Code sent successfully.",
  "data": { "expires_at": "2026-05-08T12:34:56.000000" },
  "status_code": 200
}

The plaintext code is never returned. The recipient receives it via SMS, voice call, or WhatsApp only.

Error responses (same across channels):

HTTP	Cause	Shape
400	invalid phone, send failure, unsupported `delivery_method`, WhatsApp dispatcher returned an error (e.g. `NO_DEFAULT_SENDER`, `TEMPLATE_NOT_APPROVED`)	envelope with `success: false` and a `message`
401	missing/expired `X-API-Key`	`{"detail": "Invalid or expired API key"}`
403	wrong host, API key not bound to a developer app, `app_key`/`X-App-ID` mismatch with the bound app, workspace not dev-accessible	`{"detail": "..."}`
422	malformed body (e.g. non-digit phone, missing fields)	FastAPI validation error

Behavior: invalidates the prior active OTP for (phone, app) before issuing the new one. Returns 200 only after the dispatch is accepted by the upstream provider.

Channel-specific payload & code samples

SMS
Voice call
WhatsApp

Default channel. Customisable per call via sender_id and message_template.Channel-specific fields:

Field	Type	Required	Default	Notes
`sender_id`	string	no	`OTP_DEFAULT_SENDER_ID`	The SMS sender ID shown to the recipient. Must be approved for your account.
`message_template`	string	no	server default	Must contain `{code}`. `{expiry}` is also substituted. Falls back if `{code}` missing.

Exact payload:

{
  "phone_number": "255712345678",
  "delivery_method": "sms",
  "otp_length": 6,
  "minutes_to_expire": 10,
  "sender_id": "BRIQ OTP",
  "message_template": "Your verification code is {code}. It expires in {expiry} minutes."
}

curl -X POST https://karibu.briq.tz/v1/otp/request \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "255712345678",
    "delivery_method": "sms",
    "otp_length": 6,
    "minutes_to_expire": 10,
    "sender_id": "BRIQ OTP",
    "message_template": "Your verification code is {code}. It expires in {expiry} minutes."
  }'

import requests

BASE_URL = "https://karibu.briq.tz"
API_KEY  = "YOUR_API_KEY"

resp = requests.post(
    f"{BASE_URL}/v1/otp/request",
    headers={"X-API-Key": API_KEY, "Content-Type": "application/json"},
    json={
        "phone_number": "255712345678",
        "delivery_method": "sms",
        "otp_length": 6,
        "minutes_to_expire": 10,
        "sender_id": "BRIQ OTP",
        "message_template": "Your verification code is {code}. It expires in {expiry} minutes.",
    },
    timeout=15,
)
print(resp.status_code, resp.json())

const BASE_URL = "https://karibu.briq.tz";
const API_KEY  = "YOUR_API_KEY";

const resp = await fetch(`${BASE_URL}/v1/otp/request`, {
  method: "POST",
  headers: {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    phone_number: "255712345678",
    delivery_method: "sms",
    otp_length: 6,
    minutes_to_expire: 10,
    sender_id: "BRIQ OTP",
    message_template: "Your verification code is {code}. It expires in {expiry} minutes.",
  }),
});
console.log(resp.status, await resp.json());

<?php
$baseUrl = "https://karibu.briq.tz";
$apiKey  = "YOUR_API_KEY";

$ch = curl_init("$baseUrl/v1/otp/request");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        "X-API-Key: $apiKey",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        "phone_number"      => "255712345678",
        "delivery_method"   => "sms",
        "otp_length"        => 6,
        "minutes_to_expire" => 10,
        "sender_id"         => "BRIQ OTP",
        "message_template"  => "Your verification code is {code}. It expires in {expiry} minutes.",
    ]),
]);
$response = curl_exec($ch);
$status   = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $status . "\n" . $response;

The platform calls the recipient and reads the code via TTS. There is no sender_id or message_template field — both are SMS-only and ignored on this channel.Channel-specific fields: none.Exact payload:

{
  "phone_number": "255712345678",
  "delivery_method": "call",
  "otp_length": 6,
  "minutes_to_expire": 10
}

curl -X POST https://karibu.briq.tz/v1/otp/request \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "255712345678",
    "delivery_method": "call",
    "otp_length": 6,
    "minutes_to_expire": 10
  }'

resp = requests.post(
    f"{BASE_URL}/v1/otp/request",
    headers={"X-API-Key": API_KEY, "Content-Type": "application/json"},
    json={
        "phone_number": "255712345678",
        "delivery_method": "call",
        "otp_length": 6,
        "minutes_to_expire": 10,
    },
    timeout=15,
)
print(resp.status_code, resp.json())

const resp = await fetch(`${BASE_URL}/v1/otp/request`, {
  method: "POST",
  headers: { "X-API-Key": API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    phone_number: "255712345678",
    delivery_method: "call",
    otp_length: 6,
    minutes_to_expire: 10,
  }),
});
console.log(resp.status, await resp.json());

$ch = curl_init("$baseUrl/v1/otp/request");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        "X-API-Key: $apiKey",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        "phone_number"      => "255712345678",
        "delivery_method"   => "call",
        "otp_length"        => 6,
        "minutes_to_expire" => 10,
    ]),
]);
echo curl_exec($ch);
curl_close($ch);

Delivers the OTP through the platform-managed briq_otp WhatsApp Business template. There is no sender_id or message_template field — sender resolution is automatic (see §5 behavioral rules) and the wording is fixed by the approved Meta template.Channel-specific fields: none.Exact payload:

{
  "phone_number": "255712345678",
  "delivery_method": "whatsapp",
  "otp_length": 6,
  "minutes_to_expire": 10
}

curl -X POST https://karibu.briq.tz/v1/otp/request \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "255712345678",
    "delivery_method": "whatsapp",
    "otp_length": 6,
    "minutes_to_expire": 10
  }'

resp = requests.post(
    f"{BASE_URL}/v1/otp/request",
    headers={"X-API-Key": API_KEY, "Content-Type": "application/json"},
    json={
        "phone_number": "255712345678",
        "delivery_method": "whatsapp",
        "otp_length": 6,
        "minutes_to_expire": 10,
    },
    timeout=15,
)
print(resp.status_code, resp.json())

const resp = await fetch(`${BASE_URL}/v1/otp/request`, {
  method: "POST",
  headers: { "X-API-Key": API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    phone_number: "255712345678",
    delivery_method: "whatsapp",
    otp_length: 6,
    minutes_to_expire: 10,
  }),
});
console.log(resp.status, await resp.json());

$ch = curl_init("$baseUrl/v1/otp/request");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        "X-API-Key: $apiKey",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        "phone_number"      => "255712345678",
        "delivery_method"   => "whatsapp",
        "otp_length"        => 6,
        "minutes_to_expire" => 10,
    ]),
]);
echo curl_exec($ch);
curl_close($ch);

WhatsApp-specific 400s: if the dispatcher cannot resolve a sender + APPROVED briq_otp template (e.g. the platform default isn’t configured, or a custom one is in DRAFT/PAUSED), the response is success: false with a message describing which check failed. Fall back to SMS in your client when this happens.

6.2 `POST /v1/otp/verify`

Check a code submitted by the end user. Method & path: POST https://karibu.briq.tz/v1/otp/verify Headers: X-API-Key (bound to a Developer App), Content-Type: application/json. Request body:

Field	Type	Required	Notes
`phone_number`	string (E.164 digits)	yes
`app_key`	string	no	Omit when API key is bound to a developer app. Legacy unbound keys may send this or use `X-App-ID` instead.
`code`	string	yes	plaintext code submitted by the user
`callback_url`	string (HTTPS)	no	Override or fallback if not set on request/resend
`callback_secret`	string	no	Signing secret override; secret from request/resend reused when omitted

Success 200:

{
  "success": true,
  "message": "OTP verified successfully.",
  "data": { "verified_at": "2026-05-08T12:35:21.000000" },
  "status_code": 200
}

The OTP is marked used; subsequent verifies for the same code return success: false. When a callback URL was set on request/resend or passed on verify, Karibu also sends an async flake.verified or flake.failed webhook (best-effort). See §10 Per-request flake callbacks. Handled errors (envelope, success: false):

`message`	`data.remaining_attempts`	When
`"No valid OTP found"`	`0`	no active OTP, expired, or already used
`"Invalid OTP code"`	`2`, `1`, `0`	wrong code; counter decrements
`"Max verification attempts reached"`	`0`	3rd wrong attempt — OTP is now locked
`"Invalid phone number"`	—	malformed phone

Auth/host errors (401, 403) and validation (422) are the same as on /request.

Code samples

curl -X POST https://karibu.briq.tz/v1/otp/verify \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "255712345678",
    "code": "123456"
  }'

resp = requests.post(
    f"{BASE_URL}/v1/otp/verify",
    headers={"X-API-Key": API_KEY, "Content-Type": "application/json"},
    json={
        "phone_number": "255712345678",
        "code": "123456",
    },
    timeout=10,
)
body = resp.json()
if body.get("success"):
    print("Verified at", body["data"]["verified_at"])
else:
    print("Failed:", body["message"], "remaining:", body.get("data", {}).get("remaining_attempts"))

const resp = await fetch(`${BASE_URL}/v1/otp/verify`, {
  method: "POST",
  headers: { "X-API-Key": API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    phone_number: "255712345678",
    code: "123456",
  }),
});
const body = await resp.json();
if (body.success) {
  console.log("Verified at", body.data.verified_at);
} else {
  console.log("Failed:", body.message, "remaining:", body.data?.remaining_attempts);
}

$ch = curl_init("$baseUrl/v1/otp/verify");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        "X-API-Key: $apiKey",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        "phone_number" => "255712345678",
        "code"         => "123456",
    ]),
]);
$response = curl_exec($ch);
curl_close($ch);
$body = json_decode($response, true);
if ($body["success"] ?? false) {
    echo "Verified at " . $body["data"]["verified_at"];
} else {
    echo "Failed: " . $body["message"];
}

6.3 `POST /v1/otp/resend`

Issue a new OTP after invalidating the previous one. Body shape and channel-specific fields are identical to §6.1 /request; only the path changes. Method & path: POST https://karibu.briq.tz/v1/otp/resend Success 200:

{
  "success": true,
  "message": "OTP resent successfully.",
  "data": { "expires_at": "2026-05-08T12:45:01.000000" },
  "status_code": 200
}

Error responses: identical to /request.

request vs resend — what’s the difference? Functionally both invalidate any prior active OTP and dispatch a new one. Use /resend when the end user explicitly clicks “Resend code”; this lets you treat it differently in your analytics, rate-limits, or UI without changing payloads.

Switching channels on resend is allowed — e.g. user clicks “I didn’t get the SMS, send via WhatsApp instead.” Just send the new delivery_method. The previous active OTP is invalidated regardless of which channel issued it.

Channel-specific payload & code samples

SMS
Voice call
WhatsApp

cURL

curl -X POST https://karibu.briq.tz/v1/otp/resend \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "255712345678",
    "delivery_method": "sms",
    "sender_id": "BRIQ OTP",
    "message_template": "Your verification code is {code}. It expires in {expiry} minutes."
  }'

Python

resp = requests.post(
    f"{BASE_URL}/v1/otp/resend",
    headers={"X-API-Key": API_KEY, "Content-Type": "application/json"},
    json={
        "phone_number": "255712345678",
        "delivery_method": "sms",
        "sender_id": "BRIQ OTP",
        "message_template": "Your verification code is {code}. It expires in {expiry} minutes.",
    },
    timeout=15,
)
print(resp.json())

Node.js

const resp = await fetch(`${BASE_URL}/v1/otp/resend`, {
  method: "POST",
  headers: { "X-API-Key": API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    phone_number: "255712345678",
    delivery_method: "sms",
    sender_id: "BRIQ OTP",
    message_template: "Your verification code is {code}. It expires in {expiry} minutes.",
  }),
});
console.log(await resp.json());

PHP

$ch = curl_init("$baseUrl/v1/otp/resend");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        "X-API-Key: $apiKey",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        "phone_number"     => "255712345678",
        "delivery_method"  => "sms",
        "sender_id"        => "BRIQ OTP",
        "message_template" => "Your verification code is {code}. It expires in {expiry} minutes.",
    ]),
]);
echo curl_exec($ch);
curl_close($ch);

cURL

curl -X POST https://karibu.briq.tz/v1/otp/resend \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "255712345678",
    "delivery_method": "call"
  }'

Python

resp = requests.post(
    f"{BASE_URL}/v1/otp/resend",
    headers={"X-API-Key": API_KEY, "Content-Type": "application/json"},
    json={
        "phone_number": "255712345678",
        "delivery_method": "call",
    },
    timeout=15,
)
print(resp.json())

Node.js

const resp = await fetch(`${BASE_URL}/v1/otp/resend`, {
  method: "POST",
  headers: { "X-API-Key": API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    phone_number: "255712345678",
    delivery_method: "call",
  }),
});
console.log(await resp.json());

PHP

$ch = curl_init("$baseUrl/v1/otp/resend");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        "X-API-Key: $apiKey",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        "phone_number"    => "255712345678",
        "delivery_method" => "call",
    ]),
]);
echo curl_exec($ch);
curl_close($ch);

cURL

curl -X POST https://karibu.briq.tz/v1/otp/resend \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "255712345678",
    "delivery_method": "whatsapp"
  }'

Python

resp = requests.post(
    f"{BASE_URL}/v1/otp/resend",
    headers={"X-API-Key": API_KEY, "Content-Type": "application/json"},
    json={
        "phone_number": "255712345678",
        "delivery_method": "whatsapp",
    },
    timeout=15,
)
print(resp.json())

Node.js

const resp = await fetch(`${BASE_URL}/v1/otp/resend`, {
  method: "POST",
  headers: { "X-API-Key": API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    phone_number: "255712345678",
    delivery_method: "whatsapp",
  }),
});
console.log(await resp.json());

PHP

$ch = curl_init("$baseUrl/v1/otp/resend");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        "X-API-Key: $apiKey",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        "phone_number"    => "255712345678",
        "delivery_method" => "whatsapp",
    ]),
]);
echo curl_exec($ch);
curl_close($ch);

6.4 `POST /v1/otp/invalidate`

Force-expire any active OTP for a phone scoped to your Developer App. Useful on logout, security events, or when the user changes their phone number. Method & path: POST https://karibu.briq.tz/v1/otp/invalidate Request body:

Field	Type	Required	Notes
`phone_number`	string (E.164 digits)	yes
`app_key`	string	no	Omit when API key is bound to a developer app. Legacy unbound keys may send this or use `X-App-ID` instead.

Success 200:

{
  "success": true,
  "message": "OTP invalidated successfully.",
  "data": null,
  "status_code": 200
}

Idempotent. Calling this when there is no active OTP also returns 200 — it simply has nothing to invalidate.

Code samples

curl -X POST https://karibu.briq.tz/v1/otp/invalidate \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "255712345678"
  }'

resp = requests.post(
    f"{BASE_URL}/v1/otp/invalidate",
    headers={"X-API-Key": API_KEY, "Content-Type": "application/json"},
    json={"phone_number": "255712345678"},
    timeout=10,
)
print(resp.json())

const resp = await fetch(`${BASE_URL}/v1/otp/invalidate`, {
  method: "POST",
  headers: { "X-API-Key": API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({ phone_number: "255712345678" }),
});
console.log(await resp.json());

$ch = curl_init("$baseUrl/v1/otp/invalidate");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        "X-API-Key: $apiKey",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        "phone_number" => "255712345678",
    ]),
]);
echo curl_exec($ch);
curl_close($ch);

6.5 `GET /v1/otp/status`

Inspect the currently active OTP for a phone, scoped to your Developer App, without triggering a send. Useful for UI countdowns, diagnostics, and idempotent UX (e.g. “an OTP was already sent — please check your phone”). Method & path: GET https://karibu.briq.tz/v1/otp/status Query parameters:

Param	Required	Notes
`phone_number`	yes
`app_key`	no	Omit when API key is bound to a developer app. Legacy unbound keys may send this or use `X-App-ID` instead.

Success 200:

{
  "success": true,
  "message": "OTP status retrieved.",
  "data": {
    "is_valid": true,
    "expires_at": "2026-05-08T12:45:01.000000",
    "remaining_attempts": 3
  },
  "status_code": 200
}

404 (no active OTP):

{
  "success": false,
  "message": "No active OTP found.",
  "data": null,
  "status_code": 404
}

The HTTP response body wraps status_code: 404, but the underlying HTTP response itself is 200 OK (the envelope shape applies here too). Inspect body.success and body.status_code, not the raw HTTP status, when handling this endpoint.

Code samples

curl -G https://karibu.briq.tz/v1/otp/status \
  -H "X-API-Key: YOUR_API_KEY" \
  --data-urlencode "phone_number=255712345678"

resp = requests.get(
    f"{BASE_URL}/v1/otp/status",
    headers={"X-API-Key": API_KEY},
    params={"phone_number": "255712345678"},
    timeout=10,
)
print(resp.json())

const params = new URLSearchParams({
  phone_number: "255712345678",
});
const resp = await fetch(`${BASE_URL}/v1/otp/status?${params}`, {
  headers: { "X-API-Key": API_KEY },
});
console.log(await resp.json());

$query = http_build_query([
    "phone_number" => "255712345678",
]);
$ch = curl_init("$baseUrl/v1/otp/status?$query");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ["X-API-Key: $apiKey"],
]);
echo curl_exec($ch);
curl_close($ch);

7. End-to-end flow

A typical phone-verification flow:

User enters phone in your UI → your backend calls POST /v1/otp/request with the appropriate delivery_method.
User receives SMS, voice call, or WhatsApp message with the plaintext code.
User submits code in your UI → your backend calls POST /v1/otp/verify.
- On success: true → mark phone verified, continue signup/login.
- On success: false → show error and use data.remaining_attempts to drive UX.
User clicks “Resend” → your backend calls POST /v1/otp/resend (which invalidates the prior code automatically). You may switch channels here — e.g. retry on WhatsApp after an SMS didn’t arrive.
User logs out / changes phone → your backend calls POST /v1/otp/invalidate.
Optional UI affordances: poll GET /v1/otp/status to drive countdown timers or detect that an OTP is already in-flight before issuing a new one.

For narrative walkthroughs, see Requesting OTP codes, Validating OTP codes, and Managing OTP lifecycle.

8. Error scenarios — quick reference

Scenario	HTTP	Body shape	Recommended client action
Missing/expired `X-API-Key`	401	`{"detail": "Invalid or expired API key"}`	Surface “Authentication failed” — operator should rotate the key.
API key expired	401	`{"detail": "API key expired"}`	Same — operator action.
Wrong host	403	`{"detail": "...only available for the developer domain..."}`	Fix your client’s `Host` / base URL.
API key not bound to a Developer App	403	`{"detail": "..."}` (no linked developer app)	Bind the API key to a Developer App in the dashboard or via the attach endpoint.
`app_key` / `X-App-ID` mismatch with bound key	403	`{"detail": "app_key does not match the API key's linked developer app"}` or similar	Omit `app_key` and `X-App-ID` when the key is bound; legacy unbound keys must send a matching scope.
Workspace blocks dev access	403	`{"detail": "Workspace does not allow developer access."}`	Toggle developer access for the workspace in the Briq UI.
Bad phone format	400 / 422	envelope `success: false, "Invalid phone number"` or FastAPI 422	Re-validate digits-only E.164 client-side before sending.
Unsupported `delivery_method`	400	envelope with `success: false`	Use `"sms"`, `"call"`, or `"whatsapp"`.
WhatsApp dispatcher cannot resolve sender/template	400	envelope `success: false` with `NO_DEFAULT_SENDER` / `TEMPLATE_NOT_APPROVED` in the message	Fall back to SMS automatically; surface a “try another channel” UI.
Wrong code on `/verify`	200 (envelope-400)	envelope `success: false, "Invalid OTP code", data.remaining_attempts=N`	Decrement UI counter; prompt resend at 0.
Max attempts exceeded	200 (envelope-400)	`"Max verification attempts reached"`, `remaining_attempts=0`	Force-resend; do not allow more verifies on this OTP.
OTP expired or already used	200 (envelope-400)	`"No valid OTP found"`, `remaining_attempts=0`	Prompt user to request a new OTP.
`/status` for unknown phone/app	200 (envelope-404)	envelope `success: false, status_code: 404`	Treat as “no active OTP”.
Invalid `callback_url` (HTTP, localhost, private IP)	422	FastAPI validation error (`callback_url must use https`, etc.)	Use a public HTTPS URL; test with webhook.site.

9. Best practices

Bind your API key to a Developer App. Karibu resolves the app from X-API-Key — do not send app_key in request bodies or query params in new integrations.
Never expose your API key to untrusted clients. Keep it server-side; have your frontend hit your backend, which then calls Karibu with X-API-Key only.
Never log the plaintext code. Treat it as a credential. Don’t echo it from your verify form, don’t store it in analytics, don’t include it in error reports.
Respect the 3-attempt cap in your UI. Disable the verify button after 3 failures and surface “Resend code” prominently.
Handle remaining_attempts: 0 distinctly from remaining_attempts > 0. They demand different UX (lockout vs retry).
Invalidate on logout. It’s safe to call even if you’re unsure an OTP is active.
Default to delivery_method: "sms". Use "call" for SMS-restricted regions or accessibility; use "whatsapp" for app-installed users with chat-first habits.
Cascade channels for reliability. A common pattern: try "whatsapp" first; if the dispatcher returns a 400 (template not approved, dispatcher misconfigured) fall back to "sms", and offer "call" as a manual third option.
Sender ID is SMS-only. A misconfigured sender_id may silently route through the platform default; verify deliverability with a test number before launch. The field is ignored on "call" and "whatsapp".
WhatsApp template wording is fixed. Don’t ship a UI that promises a custom message body when sending over WhatsApp — only briq_otp is dispatched, so the recipient sees the platform-approved Meta template.
Rate-limit your own users. The API does not enforce per-phone request rate limits — your application should.

See also Best practices and Security notes for cross-product guidance.

10. Per-request flake callbacks

OTP codes are internally called flakes. Optional callback_url and callback_secret on request, resend, and verify let you receive async HTTPS webhooks on verify outcomes — without registering a dashboard webhook. For a narrative walkthrough and step-by-step testing with webhook.site, see Flake lifecycle callbacks.

Fields

Field	Endpoints	Notes
`callback_url`	`request`, `resend`, `verify`	HTTPS only; no private/loopback targets. Set on `request`/`resend` to receive callbacks for that OTP window.
`callback_secret`	`request`, `resend`, `verify`	When set, callbacks include `X-Briq-Signature: sha256=<hex>`. On verify, omit to reuse the secret from request/resend.

Events

Event	When
`flake.verified`	`/verify` returns `success: true`
`flake.failed`	`/verify` hits max attempts (`reason: "max_attempts"`)

Callbacks use channel: "flake" and X-Briq-Service-Type: flake. The plaintext code is never included.

Envelope example (`flake.verified`)

{
  "id": "evt_...",
  "event": "flake.verified",
  "channel": "flake",
  "app_id": "<developer-app-uuid>",
  "created_at": "2026-06-07T12:00:00.000Z",
  "data": {
    "flake_id": "...",
    "phone_number": "255712345678",
    "status": "verified",
    "verified_at": "2026-06-07T12:00:05.000000"
  }
}

Delivery is best-effort with retries on non-2xx responses. Synchronous /verify responses are unchanged if a callback fails.

Testing in the API playground

Open POST /v1/otp/request in this reference’s interactive playground.
Set callback_url to a public HTTPS inspector URL (e.g. from webhook.site).
Optionally set callback_secret and note it for signature checks.
Call POST /v1/otp/verify with the code received on the phone.
Confirm the inspector receives flake.verified within a few seconds.

Use the same callback_url fields on POST /v1/otp/resend to set the callback target for a resent code.

11. Changelog

v1.2 — optional per-request callback_url and callback_secret on request, resend, and verify; async flake.verified and flake.failed callbacks (best-effort, signed when secret provided).
v1.1 — added WhatsApp delivery channel (delivery_method: "whatsapp"). Routes through the platform-managed briq_otp template via the WhatsApp dispatcher; sender resolution is automatic (developer-owned sender → env-pinned platform default → is_default = TRUE fallback). sender_id and message_template are ignored on this channel. /request and /resend payload tables split into channel-specific tabs.
v1 — initial public surface: request, verify, resend, invalidate, status. SMS + voice call delivery. 3-attempt cap. Single-active-OTP per (phone, app).

​1. Overview

​Channel comparison

​2. Prerequisites

​3. Authentication & host

​Base URL

​Required headers

​App scoping

​4. Standard response envelope

​5. Behavioral rules (read this first)

​6. Endpoint reference

​6.1 POST /v1/otp/request

​Channel-specific payload & code samples

​6.2 POST /v1/otp/verify

​Code samples

​6.3 POST /v1/otp/resend

​Channel-specific payload & code samples

​6.4 POST /v1/otp/invalidate

​Code samples

​6.5 GET /v1/otp/status

​Code samples

​7. End-to-end flow

​8. Error scenarios — quick reference

​9. Best practices

​10. Per-request flake callbacks

​Fields

​Events

​Envelope example (flake.verified)

​Testing in the API playground

​11. Changelog

1. Overview

Channel comparison

2. Prerequisites

3. Authentication & host

Base URL

Required headers

App scoping

4. Standard response envelope

5. Behavioral rules (read this first)

6. Endpoint reference

6.1 `POST /v1/otp/request`

Channel-specific payload & code samples

6.2 `POST /v1/otp/verify`

Code samples

6.3 `POST /v1/otp/resend`

Channel-specific payload & code samples

6.4 `POST /v1/otp/invalidate`

Code samples

6.5 `GET /v1/otp/status`

Code samples

7. End-to-end flow

8. Error scenarios — quick reference

9. Best practices

10. Per-request flake callbacks

Fields

Events

Envelope example (`flake.verified`)

Testing in the API playground

11. Changelog