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 and store it securely

Authentication Methods

Authenticate every request with your API key in the Authorization Bearer header:

Recommended

Authorization Bearer Header

Pass your API key in the Authorization: Bearer <your-key> header.

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

Using SDKs

Our official SDKs handle authentication automatically. Simply initialize the client with your API key:

JavaScript / TypeScript

javascript
import { KhaleejiAPI } from '@khaleejiapi/sdk';
 
// Initialize with your API key
const client = new KhaleejiAPI('your_api_key');
 
// All subsequent requests are automatically authenticated
const result = await client.ip.lookup('8.8.8.8');

Python

python
from khaleejiapi import KhaleejiAPI
 
# Initialize with your API key
client = KhaleejiAPI('your_api_key')
 
# All subsequent requests are automatically authenticated
result = client.ip.lookup('8.8.8.8')

Best Practices

Use Environment Variables

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

bash
# .env.local
KHALEEJI_API_KEY=your_api_key_here
 
# Then in your code:
const client = new KhaleejiAPI(process.env.KHALEEJI_API_KEY);

Use Different Keys for Each Environment

Create separate API keys for development, staging, and production environments.

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 or invalid key
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 x-api-key, 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.