API Overview

Base URLs

Authentication

Most API endpoints require authentication. The method depends on the service:

Admin Endpoints

Admin APIs use a static API key passed as a header:

curl -H "X-Admin-Key: YOUR_ADMIN_KEY" 
  https://apps.storeharmony.com/boss/api/admin/stores

User Endpoints

User-facing APIs use JWT tokens obtained via OTP verification:

# Step 1: Request OTP
curl -X POST -H "Content-Type: application/json" 
  -d '{"phone": "08012345678"}' 
  https://apps.storeharmony.com/boss/api/auth/request-otp

# Step 2: Verify OTP and get token
curl -X POST -H "Content-Type: application/json" 
  -d '{"phone": "08012345678", "code": "123456"}' 
  https://apps.storeharmony.com/boss/api/auth/verify-otp

# Step 3: Use token
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" 
  https://apps.storeharmony.com/boss/api/profile

info Token Expiry
JWT tokens are valid for 30 days. Store them securely and refresh when you get a 401 response.

Available APIs

ShopOn / BOSS Backend

PawPaw

Rate Limits

warn Rate Limit Headers
When rate limited, the API returns HTTP 429 with Retry-After header indicating seconds to wait before retrying.

Error Format

All errors follow a consistent JSON format:

{
  "error": "Human-readable error message",
  "code": "VALIDATION_ERROR",
  "details": {}
}

Common HTTP status codes:

• 400 — Bad request / validation error
• 401 — Unauthorized (missing or invalid token)
• 403 — Forbidden (insufficient permissions)
• 404 — Resource not found
• 429 — Rate limited
• 500 — Server error

SDKs & Libraries

Currently there are no official SDKs. All APIs are standard REST/JSON and can be consumed with any HTTP client:

// Node.js with fetch
const res = await fetch('https://apps.storeharmony.com/boss/api/discover/stores');
const data = await res.json();

# Python with requests
import requests
res = requests.get('https://apps.storeharmony.com/boss/api/discover/stores')
data = res.json()

tip Coming Soon
Official JavaScript and Python SDKs are in development. Star the GitHub repo to get notified.