Authentication

Authentication

Learn how to authenticate your API requests to KhaleejiAPI securely.

API Keys

KhaleejiAPI uses API keys to authenticate requests. You can view and manage your API keys in your dashboard.

Getting your API key

  1. Sign up for a free account at khaleejiapi.dev/signup
  2. Navigate to the API Keys section in your dashboard
  3. Click “Create new key” and give it a descriptive name
  4. Copy your API key — it starts with kapi_live_ and is shown only once

Authentication Method

Every request must include your API key in the Authorization header using the Bearer scheme. This is the canonical and recommended method.

Required

Authorization: Bearer <your-key>

bash
curl -X GET "https://khaleejiapi.dev/api/v1/ip/lookup?ip=8.8.8.8" \
  -H "Authorization: Bearer YOUR_API_KEY"

Common Pitfalls

These are the most frequent mistakes that cause authentication errors on the first call.

Using x-api-key as your primary integration header

Legacy clients may still be accepted when they send x-api-key, but new integrations should use the Authorization header with the Bearer scheme. Treat x-api-key as deprecated compatibility behavior, not the documented default:

bash
curl -H "Authorization: Bearer kapi_live_your_key_here" \
  https://khaleejiapi.dev/api/v1/ip/lookup

Sending the raw key without the Bearer prefix

The header value must be exactly Bearer <your-key>. Omitting Bearer or adding extra spaces returns 401.

✗ Wrong

text
Authorization: kapi_live_your_key_here

✓ Correct

text
Authorization: Bearer kapi_live_your_key_here

Wrong JS/TS SDK initialization — passing a bare string

The JavaScript/TypeScript SDK expects an options object with an apiKey property. Passing a bare string throws a runtime error.

✗ Wrong

javascript
// TypeError at runtime
const client = new KhaleejiAPI('kapi_live_...');

✓ Correct

javascript
const client = new KhaleejiAPI({
  apiKey: 'kapi_live_your_key_here',
});

Exposing the key in client-side code

Bundling your API key into a browser or mobile app makes it visible in the network tab and public source maps. Anyone who finds it can exhaust your quota. Always call the API from your backend server or use the CORS & browser integration guide for the proxy pattern.

Using SDKs

Our official SDKs handle authentication automatically. Initialize the client once with your API key and every subsequent request is authenticated for you.

JavaScript / TypeScript

typescript
import { KhaleejiAPI } from '@khaleejiapi/sdk';
 
// Pass an options object — apiKey is a required named property
const client = new KhaleejiAPI({ apiKey: 'kapi_live_your_key_here' });
 
// All subsequent requests are automatically authenticated
const result = await client.geo.lookupIp({ ip: '8.8.8.8' });

Python

python
from khaleejiapi import KhaleejiAPI
 
# Initialize with your API key
client = KhaleejiAPI("kapi_live_your_key_here")
 
# All subsequent requests are automatically authenticated
result = client.geo.lookup_ip("8.8.8.8")

Go

go
package main
 
import (
    "context"
    "fmt"
    khaleejiapi "github.com/khaleejiapi/sdk-go"
)
 
func main() {
    client := khaleejiapi.New("kapi_live_your_key_here")
    ctx := context.Background()
 
    ip, _ := client.Geo.LookupIp(ctx, "8.8.8.8")
    fmt.Println(ip.Country)
}

Swift (iOS / macOS)

swift
import KhaleejiAPI
 
let client = KhaleejiAPI(apiKey: "kapi_live_your_key_here")
 
let ip = try await client.geo.lookupIp("8.8.8.8")
print(ip.country)

Kotlin (Android / JVM)

kotlin
import dev.khaleejiapi.KhaleejiAPI
 
val client = KhaleejiAPI("kapi_live_your_key_here")
 
val ip = client.geo.lookupIp("8.8.8.8")
println(ip.country)

PHP

php
<?php
use KhaleejiAPI\KhaleejiAPI;
 
$client = new KhaleejiAPI('kapi_live_your_key_here');
 
$ip = $client->geo->lookupIp('8.8.8.8');
echo $ip['country'];
View full SDK documentation and installation instructions →

Best Practices

Use Environment Variables

Store your API key in environment variables instead of hardcoding it in source code.

bash
# .env.local  (never commit this file)
KHALEEJI_API_KEY=kapi_live_your_key_here
typescript
// JavaScript / TypeScript — pass an options object
const client = new KhaleejiAPI({ apiKey: process.env.KHALEEJI_API_KEY! });
python
# Python
import os
client = KhaleejiAPI(os.environ["KHALEEJI_API_KEY"])

Use Different Keys for Each Environment

Create separate API keys for development, staging, and production. This limits blast radius if a key leaks and makes it easy to track usage per environment.

Rotate Keys Regularly

Periodically rotate your API keys, especially if you suspect they may have been compromised.

Use Server-Side Requests

Make API calls from your backend server, not directly from client-side code.

Authentication Errors

Status CodeErrorDescription
401unauthorizedNo API key provided, invalid key, or missing Bearer prefix
403forbiddenAPI key doesn't have access to this resource
429rate_limitedToo many requests. Check rate limits.

Troubleshooting 401 Unauthorized

A 401 means we received your request but the API key was missing, malformed, or rejected. Walk this list top to bottom — most issues are caught in the first three checks.

Use Authorization: Bearer <your-key> exactly

Do not send custom auth headers, query params, or raw keys without the Bearer scheme. Use one header with one space between Bearer and your key.

No leading or trailing whitespace

When copy-pasting from the dashboard, a stray space or newline at the end of the value is the most common cause. In Bash use $KHALEEJI_API_KEY via export rather than pasting inline.

Key is active and not revoked

Open Dashboard → API Keys. The key's status badge must read Active. A revoked key returns 401 immediately and cannot be revived — create a new key instead.

Sandbox key vs live endpoint

Sandbox keys (created with the “Sandbox Mode” toggle) are limited to 10 req/min and 1,000/month against test fixtures. They will not authenticate against high-volume live data — create a non-sandbox key for production traffic.

Right project / environment

Teams often have separate keys per environment. Confirm the value in your .env matches the dashboard for this environment, not staging.

Capture the request id

Every response includes x-request-id. Include it when you contact support and we can pull the exact log line in seconds. See the troubleshooting guide for the full error catalog.

Revoke and rotate keys

Revoke a key the moment you suspect it has leaked — revocation is instant and irreversible. The full incident playbook is at /docs/security/leaked-keys. The short version:

  1. Open Dashboard → API Keys and create a replacement key first.
  2. Update your deployment's environment variable.
  3. Redeploy / restart the workers that hold the key.
  4. Click Revoke on the old key.
  5. Audit recent requests via the dashboard or GET /api/dashboard/api-keys/usage — an unfamiliar IP or country usually means the key was already abused.
  6. Add a pre-commit secret scanner (e.g. gitleaks) so the next leak is caught before it pushes.