Authentication

Every request to the KINGSTONE API must include a valid API key. Keys are issued by the Predigy team during partner onboarding.

API Key Format

Every API key starts with the ks_ prefix, followed by a random secret — for example, ks_sandbox_abc123def456.... The prefix is the same for every key; it does not encode which environment the key belongs to.

Whether your account is sandbox or production is a property of your partner account, set by Predigy when your key is issued — Predigy tells you which mode your key is for. A key belongs to exactly one account, and sandbox and production keys are not interchangeable.

Including Your API Key

Add the X-API-Key header to every request:

With curl

curl -X GET https://sandbox.kingstone.dev/api/partner/v1/games \
  -H "X-API-Key: ks_sandbox_your_key_here"

With the SDK

import { KingstoneClient } from '@kingstoneapp/sdk';

const client = new KingstoneClient({
  apiKey: 'ks_sandbox_your_key_here',
  sandbox: true,
});

// The SDK includes the X-API-Key header on every request automatically.
const { games } = await client.listGames();

How Keys Are Stored

API keys are SHA-256 hashed on the server side. KINGSTONE never stores your raw key. This means:

• If you lose your key, it cannot be recovered. You will need a new one.
• Keys are verified by hashing the value you send and comparing it to the stored hash.
• Even if the database were compromised, your raw key would not be exposed.

Error Responses

If your API key is missing, invalid, or revoked, you will receive one of these errors:

Error Code	HTTP Status	Meaning
KS-4001	401	The X-API-Key header is missing from the request.
KS-4002	401	The API key is not recognized. (Revoked keys return KS-4003; expired keys KS-4004.)

Example error response:

{
  "status": "error",
  "message": "Missing X-API-Key header",
  "errorCode": "KS-4001"
}

Security Best Practices

• Never expose your API key in frontend code. Your server should hold the key and proxy requests to KINGSTONE. Players should never see the key.
• Use environment variables to store keys. Do not hardcode them in source files.
• Rotate keys periodically. Contact Predigy to issue a new key and revoke the old one.
• Use separate keys for sandbox and production. Never test with a production key.
• Monitor the api_key.expiring webhook event to get advance notice before a key expires.

Key Management

API keys are managed by the Predigy admin team. To request a new key, rotate an existing key, or revoke a compromised key, contact your Predigy account representative.

In the future, partner self-service key management will be available through the admin dashboard.