Skip to content

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 ​

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

With the SDK ​

typescript
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 CodeHTTP StatusMeaning
KS-4001401The X-API-Key header is missing from the request.
KS-4002401The API key is not recognized. (Revoked keys return KS-4003; expired keys KS-4004.)

Example error response:

json
{
  "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.

KINGSTONE by Predigy Inc.