Iframe Configuration

Customize the iframe appearance and behavior via query parameters or the API configuration endpoint.

Query parameters

Parameter	Type	Default	Description
token	string	—	Required. Session token
locale	string	en	UI language (en, es, de, fr)
theme	string	light	Color theme (light, dark, auto)
hideHeader	boolean	false	Hide the Heuristik header bar
primaryColor	string	#317ee8	Brand primary color (hex)

Example URL

https://verify.heuristik.com?token=SESSION_TOKEN&locale=es&theme=dark&primaryColor=%23317ee8

API configuration

You can also set defaults via the Configuration API:

PUT /configuration

{
  "webhookUrl": "https://yourapp.com/webhooks/heuristik",
  "allowedOrigins": [
    "https://yourapp.com",
    "https://staging.yourapp.com"
  ],
  "riskThreshold": 75,
  "enabledModules": ["fingerprint", "liveness"]
}

Same request in YAML format (for reference)

webhookUrl: https://yourapp.com/webhooks/heuristik
allowedOrigins:
  - https://yourapp.com
  - https://staging.yourapp.com
riskThreshold: 75
enabledModules:
  - fingerprint
  - liveness

Webhook events

Event	Description
session.completed	Verification finished successfully
session.expired	Session expired before completion
fingerprint.collected	Device fingerprint data collected
risk.flagged	Risk score exceeded threshold

Webhook security

All webhook payloads include an X-Heuristik-Signature header. Verify the signature using your webhook secret to ensure authenticity.