Partner API

API Reference

Base URL: https://api.kobklein.com · All responses are JSON · TLS required

Authentication

All Partner API requests require an API key in the X-API-Key header. Live keys start with kk_live_; test keys with kk_test_.

bash

curl https://api.kobklein.com/v1/partner/verify \
  -H "X-API-Key: kk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"token": "PASSPORT_TOKEN"}'

Security

Never expose API keys in client-side code, mobile bundles, or public repos. Keys can be restricted to specific IP ranges — contact your account manager to enable IP allowlisting.

Request Signing (Optional)

For endpoints that accept sensitive data, add an X-KK-Signature header. KobKlein verifies it server-side using your shared secret.

javascript

import crypto from "crypto";

function sign(payload: object, secret: string): string {
  const body = JSON.stringify(payload);
  return crypto.createHmac("sha256", secret).update(body).digest("hex");
}

// Add to request headers:
headers["X-KK-Signature"] = sign(payload, process.env.KOBKLEIN_SIGNING_SECRET);
headers["X-KK-Timestamp"] = Date.now().toString();

Identity API

Verify a user's K-Passport token in real time. Requires identity:verify scope on your API key.

Payments API

Initiate and inspect transfers. Requires payments:write or payments:read scope.

Users API

Look up a KobKlein user by K-ID or phone. Requires users:read scope.

Webhook Configuration

Reconciliation API

Export transaction data for daily reconciliation. Requires reconciliation:read scope.

Error Codes

HTTP	code	Meaning
400	invalid_request	Missing or malformed required field
401	invalid_api_key	API key missing, revoked, or wrong format
403	insufficient_scope	API key lacks required scope for this endpoint
403	ip_not_allowed	Caller IP not in allowlist
404	not_found	Resource (user, transaction) does not exist
409	idempotency_conflict	Same Idempotency-Key used with different payload
422	token_expired	K-Passport token is past its 5-minute TTL
429	rate_limit_exceeded	Too many requests — see Rate Limits
500	internal_error	KobKlein internal error — retry with exponential backoff

Rate Limits

Endpoint group	Limit
Identity verify (POST /v1/partner/verify)	60 req / min
Payments (POST /v1/partner/payments)	120 req / min
User lookups (GET /v1/partner/users/*)	300 req / min
Reconciliation export	10 req / hour
All other endpoints	200 req / min

Rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (Unix timestamp).