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

GET /health/

Health check endpoint (no auth required)

POST /verifications/

Create verification session

Body: {"country_code": "US", "webhook_url": "optional"}
GET /verifications/{session_id}/

Get verification session details

GET /verifications/

List all verification sessions

POST /verifications/{session_id}/documents/

Upload document (multipart/form-data)

Files: file (JPEG, PNG, PDF), purpose (id_document, selfie)
GET /document-types/{country_code}/{document_type}/

Get document type schema

POST /document-types/validate/

Validate extracted document data

GET /keys/

List API keys

POST /keys/create/

Create new API key

GET /templates/{session_id}/

Get KYC HTML template

POST /webhooks/

Webhook endpoint for notifications

Example Usage

Create Verification Session
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

200 Success
201 Created
400 Bad Request
401 Unauthorized (Missing or invalid signature/timestamp)
403 Forbidden (Invalid API key or expired)
404 Not Found
500 Internal Server Error

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.