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://api.kurnl.ca/api/v1/partner/marketplace/plans/me \
  -H "X-API-Key: krnl_live_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 prefixes

PrefixEnvironment
krnl_live_Production
krnl_sb_Sandbox
Sandbox keys only work against sandbox data and cannot provision real ports.

​
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://api.kurnl.ca/api/v1/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
  • Use separate credentials for sandbox and production
  • 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

EndpointAuth method
GET /partner/marketplace/plans/meX-API-Key
GET /partner/marketplace/plans/{id}Public (no auth)
POST /partner/external-checkout/completeX-Webhook-Secret
POST /partner/external-checkout/anonymous-completeX-Webhook-Secret
POST /partner/provisioning/provider-initiatedX-API-Key
POST /partner/provisioning/bulkX-API-Key
GET /partner/provisioning/bulk/{batch_id}X-API-Key
GET /partner/reports/billingX-API-Key