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.