Authentication

Public and private keys, HMAC signing, and how to authenticate every request

Every InsightAI tenant gets three credentials at creation time (see SDKs & Integration for how to generate them). Each has a distinct purpose — using the wrong one for the wrong call is the most common integration mistake, so read this before wiring anything up.

The three credentials

Credential	Format	Used for	Where it’s used
Public API key	dpk_live_... / dpk_sandbox_...	Identifying your tenant on dashboard/admin-facing REST calls	Authorization: Bearer header
Private HMAC secret	Opaque 32+ char string	Signing every telemetry payload the SDK sends	SDK config, never sent over the wire itself
Webhook signing secret	Opaque 32+ char string	Verifying payloads InsightAI sends back to your webhook endpoint	Your webhook handler, to verify X-InsightAI-Signature

The private HMAC secret and webhook signing secret should never be embedded in client-side code beyond the SDK’s own signing logic, and never logged. The SDK signs locally — the raw secret itself doesn’t need to leave the device except inside the signature computation.

Signing outbound telemetry (SDK → InsightAI)

Every telemetry payload the SDK sends is signed with HMAC-SHA256, using your private HMAC secret, over the raw JSON request body:

X-InsightAI-Signature: base64(HMAC-SHA256(raw_request_body, hmac_secret))

Your SDK config handles this automatically — you only need to supply the secret:

InsightAiConfig(
    tenantId = "your_tenant_id",
    hmacSecretKey = "your_private_hmac_secret",
    // ...
)

If you’re calling the ingest API directly (outside an SDK, e.g. from a server-side integration), sign it yourself:

Python

import hmac, hashlib, base64, json

body = json.dumps(payload, separators=(",", ":")).encode()
signature = base64.b64encode(
    hmac.new(hmac_secret.encode(), body, hashlib.sha256).digest()
).decode()

headers = {
    "Content-Type": "application/json",
    "X-InsightAI-Signature": signature,
}

Verifying inbound webhooks (InsightAI → your backend)

When InsightAI delivers a risk.alert event to your configured webhook URL (see Webhooks & Payload Reference), verify the signature before processing the payload — never act on an unverified webhook body.

import hmac, hashlib, base64

def verify_webhook(raw_body: bytes, signature_header: str, webhook_secret: str) -> bool:
    expected = base64.b64encode(
        hmac.new(webhook_secret.encode(), raw_body, hashlib.sha256).digest()
    ).decode()
    # Constant-time comparison — never use `==` for signature checks
    return hmac.compare_digest(expected, signature_header)

Compute the signature over the raw, unparsed request body — not a re-serialized version of the parsed JSON. Re-serializing can change key ordering or whitespace and produce a signature mismatch even for a genuinely valid payload.

REST API calls (dashboard/admin endpoints)

Use your public API key as a bearer token:

curl https://api.insightsecure.ai/v1/di/alerts \
  -H "Authorization: Bearer dpk_live_..."

Key rotation

Both the HMAC secret and webhook signing secret can be rotated from the DI Dashboard under Admin → Integrations → [your tenant] → Rotate keys. Rotating invalidates the old secret immediately — coordinate a deploy so your SDK config and webhook verification update together, since there’s no overlap window where both old and new secrets are valid simultaneously.