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

KINGSTONE uses prefixed API keys so you can tell at a glance which environment a key belongs to:

Prefix	Environment	Example
ks_	Sandbox	ks_sandbox_abc123def456...
kp_	Production	kp_prod_789ghi012jkl...

Sandbox keys can only access sandbox resources. Production keys can only access production resources. They 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 '@kingstone/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 invalid, expired, or has been revoked.

Example error response:

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