Skip to main content

​
Karibu OTP API Documentation

The Karibu OTP API provides a robust solution for generating, verifying, resending, invalidating, and checking the status of One-Time Passwords (OTPs) for user authentication workflows. This API is designed to be developer-friendly, secure, and flexible for integration into various applications.

​
Authentication

All API endpoints require an X-API-Key header for authentication.
HeaderTypeRequiredDescription
X-API-KeystringYesYour API key.

​
Endpoints Overview

The Karibu OTP API supports the following endpoints:
EndpointMethodDescription
/v1/otp/requestPOSTGenerates a new OTP for a phone number.
/v1/otp/verifyPOSTVerifies an OTP entered by the user.
/v1/otp/resendPOSTResends a new OTP to a phone number.
/v1/otp/invalidatePOSTInvalidates an existing OTP.
/v1/otp/statusGETRetrieves the current status of an OTP.

​
1. Request OTP

Generate a new OTP and send it to the specified phone number.

​
Endpoint

POST /v1/otp/request

​
Request Body

FieldTypeRequiredDefaultDescription
phone_numberstringYes—Phone number in E.164 format (e.g., +255712345678).
app_keystringYes—Developer application key.
sender_idstringNoBRIQ OTPSender ID for SMS.
otp_lengthintNo6Length of the OTP code.
minutes_to_expireintNo10OTP expiry time in minutes.
delivery_methodstringNosmsDelivery method: sms or call.
message_templatestringNo—Custom message template (use {code} for OTP).

​
Request Example

{
  "phone_number": "+255712345678",
  "app_key": "devapp_123456",
  "sender_id": "BRIQ OTP",
  "otp_length": 6,
  "minutes_to_expire": 10,
  "delivery_method": "sms",
  "message_template": "Your OTP is {code}"
}

​
Response Example

{
  "success": true,
  "message": "OTP sent successfully",
  "data": {},
  "status_code": 200
}

​
2. Verify OTP

Verify an OTP entered by the user.

​
Endpoint

POST /v1/otp/verify

​
Request Body

FieldTypeRequiredDescription
phone_numberstringYesPhone number in E.164 format.
app_keystringYesDeveloper application key.
codestringYesOTP code to verify.

​
Request Example

{
  "phone_number": "+255712345678",
  "app_key": "devapp_123456",
  "code": "123456"
}

​
Response Example

{
  "success": true,
  "message": "OTP verified successfully",
  "data": {},
  "status_code": 200
}

​
3. Resend OTP

Resend a new OTP to the specified phone number.

​
Endpoint

POST /v1/otp/resend

​
Request Body

FieldTypeRequiredDefaultDescription
phone_numberstringYes—Phone number in E.164 format.
app_keystringYes—Developer application key.
sender_idstringNoBRIQ OTPSender ID for SMS.
otp_lengthintNo6Length of the OTP code.
minutes_to_expireintNo10OTP expiry time in minutes.
delivery_methodstringNosmsDelivery method: sms or call.
message_templatestringNo—Custom message template (use {code}).

​
Request Example

{
  "phone_number": "+255712345678",
  "app_key": "devapp_123456",
  "sender_id": "BRIQ OTP",
  "otp_length": 6,
  "minutes_to_expire": 10,
  "delivery_method": "sms",
  "message_template": "Your OTP is {code}"
}

​
Response Example

{
  "success": true,
  "message": "OTP resent successfully",
  "data": {},
  "status_code": 200
}

​
4. Invalidate OTP

Invalidate an existing OTP for a phone number.

​
Endpoint

POST /v1/otp/invalidate

​
Request Body

FieldTypeRequiredDescription
phone_numberstringYesPhone number in E.164 format.
app_keystringYesDeveloper application key.

​
Request Example

{
  "phone_number": "+255712345678",
  "app_key": "devapp_123456"
}

​
Response Example

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

​
5. Check OTP Status

Retrieve the current status of an OTP for a phone number.

​
Endpoint

GET /v1/otp/status

​
Query Parameters

FieldTypeRequiredDescription
phone_numberstringYesPhone number in E.164 format.
app_keystringYesDeveloper application key.

​
Response Example

{
  "success": true,
  "message": "OTP is valid",
  "data": {},
  "status_code": 200
}

​
Standard Response Format

All endpoints return responses in the following JSON format: 
{
  "success": true,
  "message": "string",
  "data": {},
  "status_code": 200
}
⌘I