API Documentation
Complete guide to integrating with Muiaa-KYC API
API Documentation
Authentication
Muiaa-KYC uses HMAC-SHA256 signature-based authentication for secure API access. Each request must include:
- Authorization header: Your API Key ID (public identifier)
- X-Signature header: HMAC-SHA256 signature of the request
- X-Timestamp header: Unix timestamp (prevents replay attacks)
# Example: Create verification session
# IMPORTANT: BODY variable must match exactly what you send in -d flag
TIMESTAMP=$(date +%s)
METHOD="POST"
API_PATH="/api/v1/verifications/"
BODY='{"country_code":"US"}'
# Use printf to create message with actual newlines
MESSAGE=$(printf "%s\n%s\n%s\n%s" "$METHOD" "$API_PATH" "$BODY" "$TIMESTAMP")
SIGNATURE=$(echo -n "$MESSAGE" | openssl dgst -sha256 -hmac "YOUR_SECRET_KEY" | cut -d' ' -f2)
curl -X POST http://kyc.muiaa.com/api/v1/verifications/ \
-H "Authorization: Bearer YOUR_API_KEY_ID" \
-H "X-Signature: sha256=${SIGNATURE}" \
-H "X-Timestamp: ${TIMESTAMP}" \
-H "Content-Type: application/json" \
-d "$BODY"
Important: The signature is computed from: METHOD\nPATH\nBODY\nTIMESTAMP
Keep your secret key secure and never expose it in client-side code or public repositories.
Note: In bash, use printf to create the message with actual
newlines.
Using echo with \n will not work correctly.
Critical: The BODY variable must match exactly (including
whitespace)
what you send in the curl -d flag. Use -d "$BODY" to ensure they
match.
Base URL
Development server:
http://kyc.muiaa.com/api/v1/
Production URL: https://api.muiaa.com/v1/
Available Endpoints
/health/
Health check endpoint (no auth required)
/verifications/
Create verification session
/verifications/{session_id}/
Get verification session details
/verifications/
List all verification sessions
/verifications/{session_id}/documents/
Upload document (multipart/form-data)
/document-types/{country_code}/{document_type}/
Get document type schema
/document-types/validate/
Validate extracted document data
/keys/
List API keys
/keys/create/
Create new API key
/templates/{session_id}/
Get KYC HTML template
/webhooks/
Webhook endpoint for notifications
Example Usage
import hmac
import hashlib
import time
import requests
import json
# Configuration
API_BASE_URL = "http://kyc.muiaa.com/api/v1"
API_KEY_ID = "ak_live_YOUR_API_KEY_ID"
SECRET_KEY = "sk_live_YOUR_SECRET_KEY"
def sign_request(secret_key: str, method: str, path: str, body: str, timestamp: str) -> str:
"""Generate HMAC-SHA256 signature for request"""
message = f"{method}\n{path}\n{body}\n{timestamp}"
signature = hmac.new(
secret_key.encode(),
message.encode(),
hashlib.sha256
).hexdigest()
return f"sha256={signature}"
def create_verification_session(country_code: str = "US"):
"""Create a new verification session"""
method = "POST"
path = "/api/v1/verifications/"
body = json.dumps({"country_code": country_code})
timestamp = str(int(time.time()))
signature = sign_request(SECRET_KEY, method, path, body, timestamp)
response = requests.post(
f"{API_BASE_URL}/verifications/",
headers={
"Authorization": f"Bearer {API_KEY_ID}",
"X-Signature": signature,
"X-Timestamp": timestamp,
"Content-Type": "application/json"
},
json={"country_code": country_code}
)
return response.json()
# Usage
result = create_verification_session("US")
print(result)
Response Examples
Verification Session Created:
{
"session_id": "vs_94c14f349b13",
"status": "created",
"country_code": "US",
"created_at": "2025-10-17T16:33:48.591272Z",
"expires_at": "2025-10-17T17:33:48.591272Z",
"kyc_template_url": "/api/v1/templates/vs_94c14f349b13"
}
API Key Created:
{
"key_id": "ak_live_FaO9lUzBPX9iYJ3ZkW2yiRUXo25QvOqo",
"key_secret": "sk_live_...",
"name": "Test Key",
"created_at": "2025-10-17T16:33:48.917721+00:00"
}
HTTP Status Codes
Rate Limits
API requests are limited to 1000 requests per hour per API key.
Rate limit information is included in response headers.
API Status: 83.3% functional (10/12 endpoints working)
All core KYC functionality is operational and ready for production use.