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.

Technical analysis update (T-1319)

Support's latest audit_onboarding() run passed signup, API key issuance, and first call execution. That indicates the core flow is healthy and that the remaining 83% first-call drop-off is mostly conversion friction, not an API outage.

  • P0 — In-product guided first call: keep users in dashboard with prefilled request examples and instant error-to-fix hints.
  • P0 — Auth mismatch reduction: enforce one canonical auth format in all first-call snippets and map 401/403 responses to exact remediation steps.
  • P1 — Endpoint confidence: keep wrong-vs-correct path examples prominent and route first-time users to one known-good starter endpoint.
  • P1 — Activation measurement loop: track drop-off by step (key created → first request attempt → first 2xx) and iterate copy + UI weekly.