Troubleshooting API Authentication & Key Errors

All requests to https://backend.sa.amwal.tech require valid merchant API credentials. If your server receives an HTTP 401 or 403 status code, use this guide to identify the root cause.

Authentication Checklist

Every API request must include the following two authentication headers:

Authorization: YOUR_SECRET_KEY
X-Amwal-Key: sandbox-amwal-xxx
Content-Type: application/json

Common HTTP 401 & 403 Scenarios

1. Sandbox vs. Production Key Mismatch

• Error: {"error": "Invalid API credentials for environment", "status": 401}
• Root Cause: You passed a sandbox-amwal-... public key alongside a Production private secret key, or sent a Sandbox key to a live production store UUID.
• Resolution:
  • Check the prefix of X-Amwal-Key:
    • Sandbox: sandbox-amwal-xxxx
    • Production: live-amwal-xxxx
  • Retrieve fresh, paired keys from Merchant Portal -> Developers -> API Keys.

2. Missing Bearer / Raw Token Prefix

• Error: {"error": "Malformed Authorization header", "status": 401}
• Resolution:
  • Pass the secret key directly as the value: Authorization: YOUR_SECRET_KEY. Confirmed live — this raw format works. Whether a Bearer YOUR_SECRET_KEY prefix is also accepted was not verified; don't rely on it until confirmed.

3. Store ID Path Mismatch

• Error: {"error": "Merchant does not have permission for store_id", "status": 403}
• Root Cause: The store_id UUID in /payment_links/{store_id}/create belongs to a different merchant organization than the authenticated API key.
• Resolution:
  • Confirm the exact store_id in your Merchant Portal dashboard under Store Settings.

Testing Your Keys

You can test your credentials immediately without writing code by opening the API Playground or running:

curl -X POST "https://backend.sa.amwal.tech/payment_links/YOUR_STORE_ID/list" \
  -H "Authorization: YOUR_SECRET_KEY" \
  -H "X-Amwal-Key: YOUR_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'