Guide

Onboarding Friction Points: First API Call Fix Guide

This page summarizes the most common onboarding blockers from the User Onboarding & First-Call Friction Audit (T-281), and the exact fixes that get first calls working quickly.

1) Use the correct authentication header

KhaleejiAPI expects the API key in the Authorization header using the Authorization: Bearer <key> format. This is the documented default for all new integrations. A legacy x-api-keyfallback may still work for older clients, but it should not be used in new code.

bash
# ❌ Wrong (raw key)
Authorization: YOUR_API_KEY
 
# ⚠ Legacy compatibility note
Older clients may still send the x-api-key header, but new integrations should not use it.
 
# ✅ Correct
Authorization: Bearer <key>

2) Call the correct endpoint path

Public REST APIs are under /api/v1. Bare /v1 paths are invalid and return 404.

bash
# ❌ Wrong path (returns 404)
https://khaleejiapi.dev/v1/email/validate
 
# ✅ Correct path
https://khaleejiapi.dev/api/v1/email/validate

3) Known-good first call

If your integration is new, run this exact request first. It confirms auth + path + response format before adding SDK abstractions.

bash
curl -X GET "https://khaleejiapi.dev/api/v1/email/[email protected]" \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json"

Common first-call issues and fixes

  • 401 Unauthorized: key sent as raw value or in x-api-key instead of Authorization: Bearer <key>.
  • 404 Not Found: using /v1/... instead of /api/v1/....
  • Unexpected validation errors: missing required query/body fields from the endpoint docs.
  • Browser/CORS failures: call KhaleejiAPI from your backend, not directly from frontend code.