Authentication

Intro

The Khaime Partner API uses API key authentication via the X-API-Key header. Key management (creating, listing, revoking keys) is a separate, more privileged flow that uses your dashboard login instead.

Context

There are two distinct auth layers, and mixing them up is the most common integration mistake:

X-API-Key — used for every actual integration call (payments, products, subscriptions, etc.), documented throughout the API Reference.
x-id-key — your merchant dashboard session token, used only by the key-management endpoints below. These are typically called from the Khaime dashboard itself, not from integration code, since they require you to already be logged in as the business owner or staff.

Hows

API Key Types

Type	Prefix	Use
Sandbox	`pk_sandbox_`	Testing — no real charges
Live	`pk_live_`	Production — real payments

Creating API Keys

Log in to app.khaime.com
Go to Settings → API & Integrations
Click Create API Key
Select environment (Sandbox or Live)
Copy the key and secret — they’re shown only once

Sandbox keys can be created by the business owner or a staff member with key-creation permission. Live keys can only be created by the business owner, and require completed KYC verification and a signed API services agreement — sandbox has neither requirement.

Using Your Key

Include the key in every request:

curl -H "X-API-Key: pk_sandbox_bff301298a..." \
     -H "Content-Type: application/json" \
     https://api.khaime.com/api/v1/products

const response = await fetch('https://api.khaime.com/api/v1/products', {
  headers: {
    'X-API-Key': process.env.KHAIME_API_KEY,
    'Content-Type': 'application/json',
  },
});

import requests

response = requests.get(
    'https://api.khaime.com/api/v1/products',
    headers={'X-API-Key': os.environ['KHAIME_API_KEY']},
)

If the key is missing, invalid, or deactivated, you’ll get a 401:

{
  "error": "Invalid API key",
  "message": "The provided API key is invalid or has been deactivated"
}

Key Management

Key management endpoints require your dashboard auth token (x-id-key header), not the API key itself. These are typically called from your dashboard, not from integration code.

Method	Endpoint	Description
POST	`/create-api-key`	Create a new API key
GET	`/sandbox`	Get (or auto-create) the business’s default sandbox key
GET	`/api-keys`	List all keys for the business
DELETE	`/api-keys/:id`	Revoke a key
PUT	`/api-keys/:id/webhook`	Set the webhook URL for a key
GET	`/api-keys/:id/webhook-secret`	Reveal the webhook secret for a key
POST	`/api-keys/:id/regenerate-webhook-secret`	Rotate a key’s webhook secret
PUT	`/api-keys/:id/toggle-status`	Enable/disable a key

Whys

Splitting the two headers exists to keep the blast radius small: an X-API-Key leaked from a server or a plugin config can only move money and read data scoped to that key’s environment — it can’t mint new keys, revoke existing ones, or change where webhooks are delivered. Only a dashboard session (x-id-key), which implies an authenticated human, can do that. Gating live-key creation behind KYC and a signed agreement, while leaving sandbox unrestricted, means you can build and test an entire integration before any compliance step blocks you — the gate only shows up when you’re ready to move real money.

Why nots

An API key is not a substitute for a dashboard login — it can’t be used to call the key-management endpoints above, on purpose. Don’t build a flow that expects a partner’s X-API-Key to rotate its own webhook secret or list sibling keys; that has to go through an authenticated dashboard session. Revoking a key is also immediate and irreversible — there’s no grace period, so coordinate any key rotation with your deployment rather than revoking the old key first.

Security Best Practices

Never expose API keys in client-side code or version control
Use environment variables to store keys
Use sandbox keys for development and testing
Rotate keys periodically
Revoke compromised keys immediately

API Reference

Account

Products & Pricing

Payments

Integration Guides

Commerce API

Subscriptions

Marketplace

Authentication

Authentication

Intro

Context

Hows

API Key Types

Creating API Keys

Using Your Key

Key Management

Whys

Why nots

Security Best Practices

​Authentication

​Intro

​Context

​Hows

​API Key Types

​Creating API Keys

​Using Your Key

​Key Management

​Whys

​Why nots

​Security Best Practices

Authentication

Intro

Context

Hows

API Key Types

Creating API Keys

Using Your Key

Key Management

Whys

Why nots

Security Best Practices