Authentication
Authenticate every request with your API key from a whitelisted IP.
Every request to /api/v1/* is authenticated with one credential: your API key, sent in the
X-Api-Key header, from a server IP you have whitelisted. There is nothing to sign.
Your API key
Generate it in your member dashboard under Developer Settings → Generate API Key. A key is
64 random characters (A–Z, a–z, 0–9) with no prefix, for example:
9fQ2xLm7RkT4wVb8NcZ1hJd6YsP3gAe0Ku5Hn2BqXo7MtW9rCv4ElSi1Fy8DpGz3
You can view it again at any time in Developer Settings (hold to reveal, then copy). We store it encrypted. The same key also signs the callbacks we send you — see Verifying a callback.
IP Whitelist Mandatory
Add at least one IP address (or CIDR range) under Developer Settings → IP Whitelist before
making any request. Requests from any other address are rejected with 403 IP_NOT_WHITELISTED,
even with a valid key.
Required Headers
Request Headers
| Parameter | Type | Required | Description |
|---|---|---|---|
X-Api-Key | String | Yes | Your 64-character API key. Required on every request. |
Content-Type | String | No | POST only, and then required: application/json. |
That is all. X-Timestamp and X-Signature are not used on requests; if you still send them,
they are ignored.
Why there is no request signing
Every request travels over TLS, which already encrypts the key and protects the request from tampering in transit, and the mandatory IP whitelist means a key copied off your server is useless from anywhere else. A signature made with that same key would add no second secret.
What every request is checked for
- Content type — a
POSTmust sendContent-Type: application/json(415 INVALID_CONTENT_TYPE). - Body size — a
POSTmust declare itsContent-Length(411) and stay within 4KB for orders (413). Every standard HTTP client setsContent-Lengthfor you. - API key — present (
401 INVALID_API_KEY, “Missing X-Api-Key header”) and valid. A malformed, unknown or revoked key gets the same401 INVALID_API_KEY(“Invalid API key”). - Reseller status — your account must be
active(403 RESELLER_INACTIVE). - IP whitelist — the calling IP must match an entry (
403 IP_NOT_WHITELISTED). - Rate limit — per tier, see Policies & Limits (
429 RATE_LIMIT_EXCEEDED). - Field-level validation — per-route allowed fields, types and size limits; unknown fields are rejected (
400 VALIDATION_ERROR).
Every response carries a unique X-Request-Id header. Quote it when you contact support.
What validation does (and does not) check
Our schema enforcement validates the request envelope only — which fields are allowed (ref_id, product_code, target, zone, price, test), their types, and their length limits. It does not validate the content of target/zone against a game’s form patterns. The validation.pattern values returned by GET /categories are helpers for your own checkout UI. A wrongly-formatted target still passes our validation and is only rejected downstream by the supply partner — the order ends as failed and the balance is automatically refunded. Validate your customer’s input on your side before ordering.
Treat it like a password
Anyone holding your key can spend your balance
Anyone with your key can place orders from your whitelisted IPs. Keep it on your server only:
- Load it from an environment variable or a secret manager. Never commit it to source control.
- Send it only in the
X-Api-Keyheader. Never put it in a URL or query string, where proxies and logs record it. - Never write it to logs, error reports or analytics.
- Never ship it in client-side code — a browser page, a mobile app or a desktop app hands it to every user.
Rotating your key
Click Regenerate API Key in Developer Settings. The old key is revoked at once — allow up
to 60 seconds for every server to drop it from its cache — after which every request still
using it gets 401 INVALID_API_KEY. Our callbacks are signed with the new key from the moment
you regenerate.
- Regenerate in Developer Settings and copy the new key.
- Deploy it to your servers.
- Switch your callback verification to the new key.
Requests made between steps 1 and 2 fail, so rotate at a quiet moment. If you suspect the key has leaked, regenerate at once and review your IP whitelist.
Key shown only as a prefix?
If Developer Settings shows only the start of your key (for example 9fQ2xLm7…) with a
“Not viewable” label, the stored key can no longer be displayed. Regenerate to get a key you can
view and copy again.
Code Examples
cURL
# Set KAYBS_API_KEY in your environment (from your secret store, not your shell history).
# GET — e.g. Balance
curl -s https://[kaybs-domain]/api/v1/balance \
-H "X-Api-Key: ${KAYBS_API_KEY}"
# POST — e.g. Order
curl -s -X POST https://[kaybs-domain]/api/v1/order \
-H "Content-Type: application/json" \
-H "X-Api-Key: ${KAYBS_API_KEY}" \
-d '{"ref_id":"R-12345","product_code":"MLBB-86","target":"12345678","zone":"1234","price":725}'
Node.js (18+)
// Save as kaybs.mjs — Node 18+ has fetch built in.
const API_KEY = process.env.KAYBS_API_KEY;
const BASE = 'https://[kaybs-domain]/api/v1';
// GET — e.g. Balance
const balanceRes = await fetch(`${BASE}/balance`, {
headers: { 'X-Api-Key': API_KEY },
});
console.log(await balanceRes.json());
// POST — e.g. Order
const orderRes = await fetch(`${BASE}/order`, {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'X-Api-Key': API_KEY },
body: JSON.stringify({
ref_id: 'R-12345',
product_code: 'MLBB-86',
target: '12345678',
zone: '1234',
price: 725,
}),
});
console.log(await orderRes.json());
PHP
<?php
function kaybs(string $method, string $path, ?array $body = null): array
{
$headers = ['X-Api-Key: ' . getenv('KAYBS_API_KEY')];
$ch = curl_init('https://[kaybs-domain]/api/v1' . $path);
if ($body !== null) {
$headers[] = 'Content-Type: application/json';
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
}
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => $method,
CURLOPT_HTTPHEADER => $headers,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 30,
]);
$raw = curl_exec($ch);
if ($raw === false) {
throw new RuntimeException(curl_error($ch));
}
return json_decode($raw, true);
}
// GET — e.g. Balance
$balance = kaybs('GET', '/balance');
// POST — e.g. Order
$order = kaybs('POST', '/order', [
'ref_id' => 'R-12345',
'product_code' => 'MLBB-86',
'target' => '12345678',
'zone' => '1234',
'price' => 725,
]);
Python
import os
import requests
API_KEY = os.environ["KAYBS_API_KEY"]
BASE = "https://[kaybs-domain]/api/v1"
HEADERS = {"X-Api-Key": API_KEY}
# GET — e.g. Balance
balance = requests.get(f"{BASE}/balance", headers=HEADERS, timeout=30).json()
# POST — e.g. Order (json= sets Content-Type and Content-Length)
order = requests.post(
f"{BASE}/order",
headers=HEADERS,
json={"ref_id": "R-12345", "product_code": "MLBB-86", "target": "12345678", "zone": "1234", "price": 725},
timeout=30,
).json()
Errors
Authentication Errors
| Parameter | Type | Required | Description |
|---|---|---|---|
INVALID_API_KEY | 401 | No | Missing X-Api-Key header, or an invalid key — also returned for a malformed or revoked key. |
RESELLER_INACTIVE | 403 | No | Your reseller account is not active. |
IP_NOT_WHITELISTED | 403 | No | The calling IP is not in your whitelist, or the whitelist is empty. |
INVALID_CONTENT_TYPE | 415 | No | A POST without Content-Type: application/json. |
PAYLOAD_TOO_LARGE | 411 / 413 | No | 411: POST sent without Content-Length. 413: body larger than allowed (4KB for orders). |
RATE_LIMIT_EXCEEDED | 429 | No | Too many requests for your tier. |
The full list is on Error Codes.