API v2 · SDK 3

Server API

These are the calls your server makes. Your web page never calls them; the browser SDK handles its side.

Base URL and auth

Base URL: https://<api-host>, shared with your keys.
Auth: send X-HEIP-SECRET-KEY: sk_live_… on every call. Never from a browser: a secret key sent from a browser is refused and recorded.
Errors are always JSON with an error code and a message. Branch on error, never on message.

POST /v2/verify

The one call most integrations need: ask HEIP about one action, with the token the page got from prepareAction.

Request. From your server.

POST /v2/verify
X-HEIP-SECRET-KEY: sk_live_…
Content-Type: application/json

{
  "sessionId": "…",
  "actionNonce": "…",
  "action": "checkout",
  "context": { "orderId": "A-1029" }
}

Field	Required	What it is
`sessionId`	Yes	From prepareAction in the page.
`actionNonce`	Yes	The single-use action token from prepareAction.
`action`	Yes	Your name for the action, for example `checkout`. Must match the token.
`policyId`	No	A built-in policy, for example `strict_withdrawal`.
`context`	No	Your own data, stored with the decision record. Use ids, not personal data.

Response. What comes back.

{
  "success": false,
  "sessionId": "…",
  "decision": "STEP_UP",
  "reasons": [ … ],
  "mode": "enforce",
  "traceId": "…"
}

Field	What it is
`success`	`true` only when `decision` is `ALLOW`.
`decision`	`ALLOW`, `STEP_UP` or `DENY`.
`reasons`	Why HEIP answered as it did. Log them; don't branch on them.
`mode`	`enforce` or `observe`. Observe mode never returns `DENY`.
`traceId`	Look up the detailed record of this decision for one hour.

Policy used: policyId if you sent one, otherwise your site's policy for that action, otherwise the default (Standard).
Single use. The token is consumed by the first call. A second call with the same token is refused as a reason, not an HTTP error.
Not idempotent, by design. Don't retry a verify that returned a decision. Retry only on a network error or 503, and expect a token-replay reason if the first call had in fact landed. To try again, get a new token from the page.
The response may include extra diagnostic fields. Log them; don't build logic on them.

POST /v2/decision/evaluate

A lower-level evaluation with the same shape as verify. The action token is required only if the policy requires it. For advanced flows, such as evaluating a session without a user action.

GET /v2/decision/:sessionId

A read-only view of the session's current standing and its versions. Nothing is stored.

GET /v2/trace/:traceId

The detailed record of one decision: the action and policy used, the token's status, the outcome and reasons, your context and the mode. Available for 1 hour. Credentials are removed. For the durable record, use the dashboard's decision history (30 days).

GET /v2/ping/server

Checks your secret key. Use it to confirm an integration before going live.

Errors

Error. Every error has this shape.

{
  "error": "invalid_secret_key",
  "message": "…"
}

HTTP	error	Meaning	What to do
400	(validation code)	The request body is malformed.	Fix the request.
401	`invalid_secret_key`	Missing, wrong, revoked or expired key (one answer for all).	Check your environment, or rotate.
403	`secret_key_exposed`	A valid secret key was sent from a browser.	Rotate the key and move the call to your server.
404	`session_not_found`	The session expired or never existed.	Ask the page for a new token.
429	`site_rate_limited`, `rate_limited`	Too many requests.	Wait for `Retry-After` seconds.
503	`session_busy`	Heavy concurrent use of one session.	Retry shortly.

Rate limits

Limits are per site, per minute. When one is exceeded, HEIP answers 429 with a Retry-After header. Limits for larger volumes are agreed with you.

Was this page clear? Tell us what was missing.