Skip to content
Book a demo

API v2 · SDK 3

Build with AI

Coding agents can add HEIP for you. Give yours the prompt below, point it at the docs index, and add the project rules so later changes stay safe.

The prompt

Paste it into Cursor, Claude Code, Codex or any other coding agent. It adds the SDK, protects one action, and stops for your real keys instead of inventing them.

  • Claude Code
  • Cursor
  • Codex

Paste this into any coding agent

Cursor, Claude Code, Codex, whatever you use. It adds the SDK, wires one protected action, and stops for your real keys.

The SDK and keys come with your HEIP account.

You're adding HEIP to this project. HEIP tells our server whether a real person is doing an important action. Get me to one verified action, nothing more.

1. Install the SDK: npm install heip-sdk (Node.js 18+). It comes with our HEIP account; if the install fails, stop and tell me.
2. Add HEIP_SITE_KEY= and HEIP_SECRET_KEY= to .env, and add .env to .gitignore. Read both from the environment. Never hardcode or print them.
3. Find the one form or button I most want to protect (ask me if it's unclear) and give the action a short name, like "checkout".
4. In the page, initialise the browser SDK with the site key. When that form is submitted, call HEIP.prepareAction("<action>") and send sessionId and actionNonce to the server with the request.
5. In the server route that handles it, before doing the work, create new HeipServer({ secretKey: process.env.HEIP_SECRET_KEY }) and call heip.verify({ sessionId, actionNonce, action }). If allow(result) is true, continue. If result.decision is "STEP_UP", return 401 and leave a TODO for the extra step. Otherwise return 403. verify throws if HEIP can't be reached: catch it and refuse the action. Log result.reasons and result.traceId.
6. Stop here and tell me to paste my keys into .env. Don't work around missing keys: no dummy values, no mocked responses.
7. When I confirm the keys are in, run the app, submit the form once, and show me the decision and mode from the server log.

Rules while you work:
- The site key may reach the browser. The secret key is server-only: never put it in client code, never log or print it.
- Call prepareAction when the protected form is submitted, not on page load. Its token works once and expires in seconds.
- Don't retry verify with the same token, and don't invent HEIP endpoints. The browser SDK handles its own calls.
- Treat any extra fields in the response as diagnostics: log them, don't branch on them.

Docs for your agent

These docs are indexed in plain text at /llms.txt, the format many AI tools read. Add that URL to your agent's docs or context settings so it looks up HEIP instead of guessing.

Project rules

Add these to the rules file your agent reads (for example AGENTS.md, CLAUDE.md or .cursor/rules) so every later change follows them.

AGENTS.md. Paste into your project's agent rules.
# HEIP in this codebase

- HEIP answers one question at the moment of an action: is a person in control? Your server asks; the browser never sees the answer.
- Site key (pk_live_…): public, lives in the page, only works on our allowed domains.
- Secret key (sk_live_…): server-only, read from HEIP_SECRET_KEY. Never in client code, logs, tests or commits.
- In the page: call HEIP.prepareAction("<action>") when the protected form is submitted, then send sessionId and actionNonce with the request.
- On the server: heip.verify({ sessionId, actionNonce, action }) before committing the action. Proceed only if allow(result).
- STEP_UP means "ask for one more step" (passkey, one-time code, review). It is not an error and not a deny.
- The token is single use. Never retry verify with the same token; get a new token from the page.
- The server SDK fails closed. Only use onError: "allow" for low-risk actions, and say so in a comment.
- Log result.reasons and result.traceId next to our own ids. Don't branch on diagnostic fields.
- Don't call or document HEIP's browser endpoints; the SDK owns them.

Review what it wrote

Before you merge, check:

  • The secret key is read from the server environment only, and appears nowhere in client code, logs, tests or commits.
  • prepareAction runs when the form is submitted, not on page load.
  • The server calls verify before it commits the action, and refuses when verify throws.
  • STEP_UP leads to an extra step, not an error page.
  • Reasons and the trace id are logged next to your own ids.
  • No made-up endpoints, no mocked HEIP responses left in the code.

Was this page clear? Tell us what was missing.