Authentication

kurnl uses two authentication mechanisms. Which one you use depends on the direction of the API call.

API Key — your calls to kurnl

Use your API key when you are calling kurnl’s API directly (subscriber management, plan queries, bulk provisioning). Send it in the X-API-Key header:

curl https://middleware.bso-projects.com/partner/marketplace/plans/me \
  -H "X-API-Key: krnl_a1b2c3d4e5f6..."

API keys are scoped to your provider account. You cannot access another provider’s subscribers or plans with your key.

Never expose your API key in client-side code (browser JavaScript, mobile apps). All calls using X-API-Key must be made from your server.

Key format

Your API key is a single production credential of the form krnl_<hex>. There is no separate sandbox key — the partner API operates on your live account. For safe, no-impact exploration use the in-dashboard sandbox instead.

Rotating keys

Keys can be rotated from Dashboard → Settings → API Keys. Old keys stop working immediately on rotation. There is no grace period.

Webhook Secret — kurnl’s calls to you (CKO-03)

The webhook secret is used for CKO-03 external checkout callbacks. When your checkout system calls kurnl’s /external-checkout/complete endpoint, kurnl looks up the secret for your service_provider_document_id and verifies the X-Webhook-Secret header before processing anything.

curl -X POST https://middleware.bso-projects.com/partner/external-checkout/complete \
  -H "X-Webhook-Secret: your-pre-shared-secret" \
  -H "Content-Type: application/json" \
  -d '{ "service_provider_document_id": "...", ... }'

This secret is also used to sign outbound webhook events kurnl sends to your webhook_url. See Webhooks for signature verification.

The webhook secret is a symmetric pre-shared value — it is never hashed or encrypted at rest on kurnl’s side. Treat it like a password: at least 32 random characters, rotated if compromised.

Keeping credentials safe

Store both the API key and webhook secret as environment variables, never in source code
Treat the API key as a production credential — the partner API has no sandbox mode
Restrict server access to the IP ranges of your checkout and back-office servers where possible
If a credential is compromised, rotate it immediately from the dashboard and audit recent API activity in your logs

Which credential for which endpoint

Endpoint	Auth method
`GET /partner/marketplace/plans/me`	`X-API-Key` (`krnl_...`)
`GET /partner/marketplace/plans/{id}`	Public (no auth)
`POST /partner/external-checkout/complete`	`X-Webhook-Secret`
`POST /partner/external-checkout/anonymous-complete`	`X-Webhook-Secret`
`POST /partner/provisioning/provider-initiated`	`X-API-Key`
`POST /partner/provisioning/bulk`	`X-API-Key`
`GET /partner/provisioning/bulk/{batch_id}`	`X-API-Key`
`GET /partner/reports/billing`	`X-API-Key`

Getting Started

Operator Guides

Integration Guides

AI Support Agent

API Key — your calls to kurnl

Key format

Rotating keys

Webhook Secret — kurnl’s calls to you (CKO-03)

Keeping credentials safe

Which credential for which endpoint

​API Key — your calls to kurnl

​Key format

​Rotating keys

​Webhook Secret — kurnl’s calls to you (CKO-03)

​Keeping credentials safe

​Which credential for which endpoint

API Key — your calls to kurnl

Key format

Rotating keys

Webhook Secret — kurnl’s calls to you (CKO-03)

Keeping credentials safe

Which credential for which endpoint