Authentication

Auth Test Endpoint

A lightweight endpoint for validating an API key's authenticity without consuming any rate-limit or monthly quota allowance. Use it from your dashboard “Test Connection” flow, CI pipelines, or any context where you need to confirm a key is valid before issuing real API calls.

POST /api/v1/auth/test

Requires API key

Validates the supplied API key and returns whether the key is a live or sandbox (test) key. The check bypasses rate-limit counters and monthly quota meters, so it does not affect your usage statistics or billing.

Endpoint:/api/v1/auth/test
Method:POST
Auth:Required
Quota impact:None
Latency:<30ms

Request headers

HeaderRequiredDescription
AuthorizationYesBearer <your-api-key> — the key to validate

cURL

bash
curl -X POST "https://khaleejiapi.dev/api/v1/auth/test" \
  -H "Authorization: Bearer ******"

Response — valid live key (HTTP 200)

json
{
  "data": {
    "valid": true,
    "keyType": "live"
  },
  "meta": { "timestamp": "2025-07-01T12:00:00.000Z" }
}

Response — valid sandbox (test) key (HTTP 200)

Keys that start with kapi_test_ are sandbox keys. The keyType field reflects this so your application can warn users who accidentally supply a test key in a production environment.

json
{
  "data": {
    "valid": true,
    "keyType": "test"
  },
  "meta": { "timestamp": "2025-07-01T12:00:00.000Z" }
}

Response — invalid or missing key (HTTP 401)

json
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key"
  }
}

Response fields

FieldTypeDescription
data.validbooleanAlways true when the request succeeds (HTTP 200).
data.keyTypestring"live" for production keys (kapi_live_…) or "test" for sandbox keys (kapi_test_…).
meta.timestampstringISO 8601 server timestamp of the response.

Rate-limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) are included in every 200 response even though this endpoint does not decrement the remaining counter.

Code examples

JavaScript / TypeScript

javascript
const response = await fetch("https://khaleejiapi.dev/api/v1/auth/test", {
  method: "POST",
  headers: {
    "Authorization": "Bearer ******",
  },
});
 
const { data } = await response.json();
 
if (response.ok && data.valid) {
  console.log("Key is valid —", data.keyType); // "live" or "test"
} else {
  console.error("Authentication failed:", response.status);
}

Python

python
import httpx
 
response = httpx.post(
    "https://khaleejiapi.dev/api/v1/auth/test",
    headers={"Authorization": "Bearer ******"},
)
 
if response.status_code == 200:
    data = response.json()["data"]
    print(f"Key is valid — {data['keyType']}")  # "live" or "test"
else:
    print("Authentication failed:", response.status_code)

Error reference

HTTP statusError codeCause
401INVALID_API_KEYThe supplied API key is missing, malformed, or not recognised.
500INTERNAL_ERRORContext initialisation failed on the server. Rare; retry once.

When to use this endpoint

  • Dashboard “Test Connection” buttons — confirm the user's key is valid before saving it to your configuration store.
  • CI/CD pipelines — verify that a secret environment variable contains a valid key at deploy time without making a billable API call.
  • SDK initialisation — check once at startup that the configured key is live (not accidentally a sandbox key) before serving production traffic.
  • Key rotation workflows — confirm the new key is accepted before revoking the old one.

Do not use this endpoint as a keep-alive probe or high-frequency ping. Use /api/v1/ping (no auth, <5 ms, documented on the Health & Liveness page) for that purpose.

Related

Authentication

How to authenticate every API request with Authorization: Bearer.

Health & Liveness

Unauthenticated ping and authenticated health endpoints for uptime monitors.

Debugging & Support

Include X-Request-ID when contacting support

Every response from KhaleejiAPI includes an X-Request-ID header — a unique identifier that lets our support team pull the exact log entry for your request within seconds. Always share it when reporting an unexpected error or unexpected result.

How to capture it

JavaScript / fetch

const res = await fetch("https://khaleejiapi.dev/api/v1/...", {
  headers: { Authorization: "******" },
});
const requestId = res.headers.get("x-request-id");
console.log("Request ID:", requestId);
// → e.g. "req_01j9xkz4vp8..."

cURL

curl -si "https://khaleejiapi.dev/api/v1/..." \
  -H "Authorization: ******" | grep -i x-request-id
# → x-request-id: req_01j9xkz4vp8...

Browser DevTools

Open DevTools (F12) → Network tab → click the failing request → scroll to the Response Headers section → copy the value next to x-request-id.

For a full list of error codes and guidance on common issues, see the Troubleshooting guide.