Skip to content

USAGE.md

Latest commit

 

History

History
170 lines (123 loc) · 2.95 KB

USAGE.md

File metadata and controls

170 lines (123 loc) · 2.95 KB
Raw

API Usage Guide

Prerequisites

make setup && make migrate-up && make run

Server: http://localhost:8080

Note

Requires Interface API instance and Matrix token (mt_xxxxx). See Interface API docs for setup.

Configuration

Configure Interface API in .env:

INTERFACE_API_URL=http://localhost:8080
INTERFACE_API_TOKEN=mt_xxxxx

See SECURITY.md for production configuration.

Authentication

The API supports optional Bearer token authentication using Matrix tokens. When a valid Matrix token is provided:

  • The token is used to authenticate with the Interface API
  • The sender field can be specified to control which device sends the OTP

Without authentication:

  • The default Interface API token from environment variables is used
  • The first available device for the platform is used as sender

API Endpoints

Generate OTP

Basic Usage (No Authentication):

curl -X POST http://localhost:8080/api/v1/otp/generate \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+237123456780",
    "platform": "wa"
  }'

With Matrix Token Authentication:

curl -X POST http://localhost:8080/api/v1/otp/generate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer mt_xxxxx" \
  -d '{
    "phone_number": "+237123456780",
    "platform": "wa",
    "sender": "+237123456789"
  }'

Request Fields:

  • phone_number (required): International phone number (E.164 format)
  • platform (required): Platform identifier (e.g., "wa" for WhatsApp)
  • sender (optional): Specific device/number to send from (only used when authenticated)

Response:

{
  "message": "OTP sent successfully",
  "expires_at": "2026-03-17T11:35:00Z"
}

Verify OTP

curl -X POST http://localhost:8080/api/v1/otp/verify \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+237123456780",
    "platform": "wa",
    "code": "123456"
  }'

Response:

{
  "message": "OTP verified successfully"
}

List Platforms

Basic Usage (No Authentication):

curl -X GET http://localhost:8080/api/v1/platforms

With Matrix Token Authentication:

curl -X GET http://localhost:8080/api/v1/platforms \
  -H "Authorization: Bearer mt_xxxxx"

Response:

[
  {
    "platform": "wa",
    "device_id": "+237123456789"
  }
]

Error Responses

400 - Bad Request:

{
  "error": "Missing required field: phone_number"
}

401 - Unauthorized:

{
  "error": "Invalid or expired OTP"
}

401 - Unauthorized (Invalid Token):

{
  "error": "invalid authorization header format"
}

403 - Forbidden:

{
  "error": "invalid or expired token"
}

429 - Too Many Requests:

{
  "error": "Too many attempts, please request a new code"
}

API Reference

Swagger UI: http://localhost:8080/docs/index.html