Karibu OTP API

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

​

1. Overview

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

​

Channel comparison

​

2. Prerequisites

• A Briq account with a workspace.
• An active developer API key (X-API-Key). Generate one in the Briq dashboard.
• At least one Developer App registered against your workspace. Each app gives you:
  • app_id — UUID, used optionally in the X-App-ID header.
  • app_key — string token, sent in the body of every OTP request.
• 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).

​

3. Authentication & host

​

Base URL

https://karibu.briq.tz

​

Required headers

​

App-scoping rules

• The app_key must resolve to a Developer App you own.
• If your X-API-Key is bound to a specific Developer App, the body’s app_key must resolve to the same app — otherwise you get 403 (app_key does not match the API key's linked developer app).
• The Developer App’s workspace must allow developer access for your user — otherwise 403 (Workspace does not allow developer access.).

​

4. Standard response 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.

​

5. Behavioral rules (read this first)

​

6. Endpoint reference

​

6.1 POST /v1/otp/request

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

​

Channel-specific payload & code samples

{
  "phone_number": "255712345678",
  "app_key": "YOUR_APP_KEY",
  "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",
    "app_key": "YOUR_APP_KEY",
    "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."
  }'

{
  "phone_number": "255712345678",
  "app_key": "YOUR_APP_KEY",
  "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",
    "app_key": "YOUR_APP_KEY",
    "delivery_method": "call",
    "otp_length": 6,
    "minutes_to_expire": 10
  }'

{
  "phone_number": "255712345678",
  "app_key": "YOUR_APP_KEY",
  "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",
    "app_key": "YOUR_APP_KEY",
    "delivery_method": "whatsapp",
    "otp_length": 6,
    "minutes_to_expire": 10
  }'

​

6.2 POST /v1/otp/verify

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

​

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",
    "app_key": "YOUR_APP_KEY",
    "code": "123456"
  }'

​

6.3 POST /v1/otp/resend

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

​

Channel-specific payload & code samples

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",
    "app_key": "YOUR_APP_KEY",
    "delivery_method": "sms",
    "sender_id": "BRIQ OTP",
    "message_template": "Your verification code is {code}. It expires in {expiry} minutes."
  }'

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

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",
    app_key: APP_KEY,
    delivery_method: "sms",
    sender_id: "BRIQ OTP",
    message_template: "Your verification code is {code}. It expires in {expiry} minutes.",
  }),
});
console.log(await resp.json());

$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",
        "app_key"          => $appKey,
        "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 -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",
    "app_key": "YOUR_APP_KEY",
    "delivery_method": "call"
  }'

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

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",
    app_key: APP_KEY,
    delivery_method: "call",
  }),
});
console.log(await resp.json());

$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",
        "app_key"         => $appKey,
        "delivery_method" => "call",
    ]),
]);
echo curl_exec($ch);
curl_close($ch);

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",
    "app_key": "YOUR_APP_KEY",
    "delivery_method": "whatsapp"
  }'

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

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",
    app_key: APP_KEY,
    delivery_method: "whatsapp",
  }),
});
console.log(await resp.json());

$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",
        "app_key"         => $appKey,
        "delivery_method" => "whatsapp",
    ]),
]);
echo curl_exec($ch);
curl_close($ch);

​

6.4 POST /v1/otp/invalidate

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

​

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",
    "app_key": "YOUR_APP_KEY"
  }'

​

6.5 GET /v1/otp/status

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

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

​

Code samples

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

​

7. End-to-end flow

1. User enters phone in your UI → your backend calls POST /v1/otp/request with the appropriate delivery_method.
2. User receives SMS, voice call, or WhatsApp message with the plaintext code.
3. 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.
4. 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.
5. User logs out / changes phone → your backend calls POST /v1/otp/invalidate.
6. 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.

​

8. Error scenarios — quick reference

​

9. Best practices

• 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.
• Do not ship app_key to untrusted clients. Hold it server-side; have your frontend hit your backend, which then calls Karibu.
• 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.

​

10. Changelog

• 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).