Sign in with HEVN

Sign in with HEVN is how a client comes to exist. Your customer signs in to a HEVN-hosted popup on your site — with Google, or with a one-time code sent to an email you pass — and your backend exchanges the code that comes back for a cl_… id. Signing in through your session is the consent: there is no separate screen to allow access. The same popup is where the account holder later approves each payout you book for them and, for an individual, verifies their identity. The window takes nothing from your page but the session URL your server got from HEVN, and optionally the email to sign in with. It shows no HEVN product screens: a sign-in, then, for a payout, the terms being approved, or, for a verification, the identity check.

Before you start

Your integrator account is active. HEVN switches it on. Until it does, POST /dapi/v1/connect/sessions and POST /dapi/v1/clients/link answer 403 client_creation_not_enabled — see Going live.
Your site is an allowed origin. In the HEVN app, open Settings → Partner program → Developer and find the Sign-in window card. Add every origin your callback page is served from under Allowed sites. A session for any other redirectUri is refused.
You have a callback page. One static page on an allowed origin that hands the popup’s result back to the page that opened it. It is shown below.

Configure the window

The Sign-in window card holds one setting: Allowed sites, up to 20 origins the window may return to — https://host, or http://localhost:<port> and http://127.0.0.1:<port> for development, with no path and no query. With none, no session can be created. Removing an allowed site also stops every session already issued for it: the window refuses to open a session whose redirectUri is no longer on the list. How the window looks — its title, logo, colours and theme — is set by HEVN on request; ask HEVN support. Nothing about the window is configurable from the API or from the session URL: a page that opens the popup cannot restyle it, retitle it or redirect it.

Link an account

Browsers block a popup that is not opened synchronously by a user gesture. Open an empty window first, inside the click handler and before any await, then ask your server for the session and point the window at it.

Browser

button.addEventListener("click", async () => {
  const popup = window.open("about:blank", "hevn-connect", "popup,width=460,height=720");
  if (!popup) return showError("Allow pop-ups for this site to sign in.");

  const { url } = await (await fetch("/hevn/link/start", { method: "POST" })).json();
  const result = await hevnResult(url, popup);           // below
  if (result.error) return showError(result.error);

  await fetch("/hevn/link/finish", {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({ code: result.code, state: result.state }),
  });
});

2. Create a session on your server

POST /dapi/v1/connect/sessions is called with your own access token and no X-Hevn-Account — it is about your integrator account, so the header answers 400 account_scope_conflict.

curl -X POST "$HEVN_API/connect/sessions" \
  -H "Authorization: Bearer $HEVN_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"link","redirectUri":"https://app.example.com/hevn/callback"}'

session = hevn.post("/connect/sessions", {
    "action": "link",
    "redirectUri": "https://app.example.com/hevn/callback",
})

const session = await hevn.post("/connect/sessions", {
  action: "link",
  redirectUri: "https://app.example.com/hevn/callback",
});

session, err := api.Post("/connect/sessions", hevn.Body{
	"action":      "link",
	"redirectUri": "https://app.example.com/hevn/callback",
})

Response — 201

{
  "url": "https://sandbox.gethevn.com/connect?session=eyJhbGciOiJFUzI1NiIs…",
  "state": "pQ8v2Zr0cJ3mX7tLkN1wA5yHs9dE4fBq",
  "expiresAt": "2026-09-17T10:14:11Z"
}

string

required

link asks the account holder to connect their account. sign asks them to approve one payout — see Approve a payout. verify asks a linked individual to verify their identity — see Verify an individual.

string

required

The page the window returns to. An https:// URL — or http://localhost and http://127.0.0.1 in development — with no fragment, on an origin listed under Allowed sites. Any other origin answers 403 redirect_uri_not_allowed.

string

The po_… to approve. Required for sign, refused otherwise.

string

The cl_… whose holder verifies their identity. Required for verify, refused otherwise.

url opens the window and lives for about ten minutes, until expiresAt. HEVN signs it, and it is bound to your integrator account, the action, the payout or client, the redirectUri and a one-time nonce. state is that nonce: the window sends it back on redirectUri with the result, and nothing else ties the result to this session. Give url to the browser and keep state on your side.

3. Bind the session to this browser

Never let the browser tell your server which client it is. Remember state in an HttpOnly cookie when you create the session, and accept a code only when the browser returns the same state in that same cookie jar. A code arriving with no cookie, or with another state, came from somewhere else.

Node

app.post("/hevn/link/start", async (req, res) => {
  const session = await hevn.post("/connect/sessions", {
    action: "link",
    redirectUri: "https://app.example.com/hevn/callback",
  });
  res.cookie("hevn_link", sign({ state: session.state }), {
    httpOnly: true, secure: true, sameSite: "lax", path: "/hevn/link", maxAge: 10 * 60_000,
  });
  res.json({ url: session.url });
});

When your product already knows the customer’s email, add it to the session URL as login_hint before you navigate the popup:

Browser

const opened = new URL(url);
opened.searchParams.set("login_hint", "[email protected]");
popup.location.href = opened.toString();

The window then sends a one-time code to that address and signs in with it; the holder cannot change the address in the window. Without login_hint the window offers Google and email sign-in. login_hint only chooses how the holder signs in — it is not part of the signed session, so never treat it as proof of who signed in. POST /dapi/v1/clients/link answers the account that actually did.

4. Exchange the code

The window returns a code that lives for five minutes and works only for your integrator account. Exchange it server-side, again with no X-Hevn-Account:

curl -X POST "$HEVN_API/clients/link" \
  -H "Authorization: Bearer $HEVN_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code":"eyJhbGciOiJFUzI1NiIs…"}'

client = hevn.post("/clients/link", {"code": code})

app.post("/hevn/link/finish", async (req, res) => {
  const attempt = verify(req.cookies.hevn_link);
  res.clearCookie("hevn_link", { path: "/hevn/link" });
  if (!attempt || !timingSafeEqual(attempt.state, req.body.state)) {
    return res.status(400).json({ code: "state_mismatch" });
  }
  const client = await hevn.post("/clients/link", { code: req.body.code });
  req.session.clientId = client.id;      // your own signed session, never a browser field
  res.json({ signedIn: true });
});

client, err := api.Post("/clients/link", hevn.Body{"code": code})

Response — 200

{
  "id": "cl_7YQ2Kf3mN8",
  "status": "ready",
  "email": "[email protected]",
  "baseSmartWallet": "0x2f1c9a3b7e5d41c8a06f2d9b4e7c15839af0d6b2",
  "kybStatus": "notStarted",
  "createdAt": "2026-09-17T10:04:11Z",
  "pollUrl": "/dapi/v1/client"
}

The answer is the client record. Store id against your own user. From now on your server finds the client from its own session and sends that id in X-Hevn-Account; the browser never carries it, so no page can ask your server to act for somebody else’s account. Exchanging the same code again returns the same client.

The callback page

The window finishes by navigating to redirectUri with the result in the query string: code or error for a link, status, payout and reference or error for a payout, status or error for a verification, and state on every one. The callback page posts that query to the page that opened the popup over a BroadcastChannel, then closes the window.

callback.html

<!doctype html>
<meta charset="utf-8">
<title>Signing in…</title>
<script>
  const result = Object.fromEntries(new URLSearchParams(location.search));
  if (result.state) {
    const channel = new BroadcastChannel("hevn-connect");
    channel.postMessage({ state: result.state, result });
    channel.close();
    window.close();
  }
</script>

The opener listens on the same channel and settles only on the result that carries its own session’s state:

Browser

function hevnResult(url, popup, timeoutMs = 10 * 60_000) {
  const token = new URL(url).searchParams.get("session");
  const body = token.split(".")[1].replace(/-/g, "+").replace(/_/g, "/");
  const { nonce } = JSON.parse(atob(body.padEnd(Math.ceil(body.length / 4) * 4, "=")));
  const channel = new BroadcastChannel("hevn-connect");
  return new Promise((resolve, reject) => {
    const timer = setTimeout(() => { channel.close(); reject(new Error("timeout")); }, timeoutMs);
    channel.onmessage = ({ data }) => {
      if (data?.state !== nonce) return;
      clearTimeout(timer);
      channel.close();
      resolve(data.result);
    };
    popup.location.href = url;
  });
}

The result does not travel through window.opener. Google’s sign-in cuts the popup off from the page that opened it, so by the time the window returns, window.opener is null. A BroadcastChannel reaches every page of your origin in the same browser, which is why the callback page must live on the same origin as the page that opened the popup. state on the result is the nonce inside the session token, and it equals the state field POST /dapi/v1/connect/sessions answered. The browser check only routes the result to the right page; the check that matters is your server’s, against its cookie.

The Node reference at hevn-inc/dapi-sdk ships this browser half as HevnConnect: HevnConnect.open() opens the popup synchronously in the click handler, .link(url), .sign(url) and .run(url) navigate it and resolve with the result, and HevnConnect.complete() is the whole callback page. Like the rest of that repository, it is a working reference to read, not a supported package.

Who can be linked

Only an account created in the sign-in window can be linked. The window signs out any HEVN session in that browser before every link sign-in, so the holder always chooses the account explicitly, and:

The person signing in	What happens
Has no HEVN account	The sign-in creates one and the window returns a `code`.
Already linked to you through an earlier sign-in	They sign in again and the window returns a new `code` for the same client. This is how a returning customer logs in to your product.
Already has a HEVN account of their own	The window refuses with `already_registered` and offers to open HEVN instead. An account someone already uses directly can never be handed to an integrator.
Is linked to another integrator	The window refuses with `already_linked`.

The window names your product and says what signing in gives you: you can see balances, open accounts and prepare transfers, and the holder approves every transfer themselves in this window.

Approve a payout

A payout you book for a linked client answers authorization: "client" and carries no approval for your key. The holder signs it. Create a sign session for that payout and open the popup exactly as for a link:

curl -X POST "$HEVN_API/connect/sessions" \
  -H "Authorization: Bearer $HEVN_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"sign","payoutId":"po_6d21…","redirectUri":"https://app.example.com/hevn/callback"}'

session = hevn.post("/connect/sessions", {
    "action": "sign",
    "payoutId": payout["id"],
    "redirectUri": "https://app.example.com/hevn/callback",
})

const session = await hevn.post("/connect/sessions", {
  action: "sign",
  payoutId: payout.id,
  redirectUri: "https://app.example.com/hevn/callback",
});

session, err := api.Post("/connect/sessions", hevn.Body{
	"action":      "sign",
	"payoutId":    payout.Str("id"),
	"redirectUri": "https://app.example.com/hevn/callback",
})

The payout must belong to a client linked to you and still be awaitingSignature. Otherwise the session is refused with 404 payout_not_found or 409 payout_not_awaiting_signature. In the window the holder signs in — a HEVN session already open in that browser is reused for sign — sees the amount, the contact’s name and who requested it, and their own wallet signs the debit. The callback receives status=submitted, payout=po_… and, when the debit was sent, reference. A payout that was no longer waiting by the time the window opened comes back with its current status and nothing signed. The redirect is a hint, never the record. Read GET /dapi/v1/payouts/{payoutId} with the client in X-Hevn-Account and follow it to settled like any other payout — see Payouts.

Verify an individual

A linked individual verifies their own identity, in this window, after signing in to their own account. You never receive a verification link: whoever opens one submits documents onto that account, so it stays with the holder. A business client verifies through Onboarding instead. You need it when a virtual account the client requested waits on verification_required (Virtual accounts). Create a verify session for the client and open the popup exactly as for a link:

curl -X POST "$HEVN_API/connect/sessions" \
  -H "Authorization: Bearer $HEVN_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"verify","clientId":"cl_7YQ2Kf3mN8","redirectUri":"https://app.example.com/hevn/callback"}'

session = hevn.post("/connect/sessions", {
    "action": "verify",
    "clientId": client_id,
    "redirectUri": "https://app.example.com/hevn/callback",
})

const session = await hevn.post("/connect/sessions", {
  action: "verify",
  clientId,
  redirectUri: "https://app.example.com/hevn/callback",
});

session, err := api.Post("/connect/sessions", hevn.Body{
	"action":      "verify",
	"clientId":    clientID,
	"redirectUri": "https://app.example.com/hevn/callback",
})

The client must be linked to you, or the session is refused with 404 client_not_found — the same answer for an id that does not exist. A business client answers 409 verification_not_applicable. A client that is already verified is not refused: the window says so and returns status=approved. In the window the holder signs in, and must sign in to that same account — any other answers account_mismatch. The identity check runs inside the window. When the holder finishes or closes it, the callback receives status:

`status`	Meaning
`approved`	Verified.
`inReview`	Submitted and being reviewed.
`actionRequired`	Something is still missing; open a new `verify` session when the holder is ready.
`rejected`	Refused.
`notStarted`	The holder left before submitting anything.

The redirect is a hint, never the record. Read GET /dapi/v1/client with the client in X-Hevn-Account: verifiedAt is set once the identity is verified, and stays absent until then. A review can take a while after the window closes, so poll the client or GET /dapi/v1/banks/{product} — the verification_required blocker goes away and the virtual account moves on by itself.

In the sandbox the window runs against a test verification provider, so the whole flow works with test documents. For automated tests, POST /dapi/v1/sandbox/kyb/status with {"status": "approved"} verifies an individual client directly — see Sandbox.

Errors

Refusals come from two places. Your server sees the API’s; your callback page sees the window’s, as error on the redirect.

Where	`code`	Cause	What to do
`POST /connect/sessions`	`403 redirect_uri_not_allowed`	The origin of `redirectUri` is not under Allowed sites	Add the origin in the Sign-in window card, or fix the URL
`POST /connect/sessions`	`422 validation_failed`	`redirectUri` is not `https://` (or local `http://`), carries a fragment, `payoutId` is missing for `sign` or present otherwise, or `clientId` is missing for `verify` or present otherwise	Fix the body
`POST /connect/sessions`	`404 client_not_found`, `409 verification_not_applicable`	A `verify` session for a client that is not linked to you, or that is a business	Verify a business through Onboarding
`POST /connect/sessions`	`404 payout_not_found`, `409 payout_not_awaiting_signature`	A `sign` session for a payout that is not a linked client’s, or that no longer waits for a signature	Read the payout before you open the window
`POST /connect/sessions`, `POST /clients/link`	`403 client_creation_not_enabled`	Your integrator account is not active	Ask HEVN — see Going live
`POST /clients/link`	`400 link_code_invalid`	The code is malformed, was issued for another integrator, or the account is gone	Start a new sign-in
`POST /clients/link`	`410 link_code_expired`	The code is older than five minutes	Start a new sign-in
`POST /clients/link`	`409 client_already_linked`	The account is already connected to another integrator, or can no longer be connected to you	Nothing to retry. Tell your customer
Callback	`access_denied`	The holder cancelled in the window	Let them try again when they are ready
Callback	`already_registered`	The Google account already has a HEVN account of its own	It cannot be linked. Ask your customer to sign in with another Google account
Callback	`already_linked`	The account is connected to another integrator	Nothing to retry
Callback	`account_mismatch`	A `verify` session where the holder signed in to a different account than the session’s client	Ask the holder to sign in with the account they linked
Callback	`not_found`	The signed-in holder does not own the payout, or it is not linked to you — usually the wrong Google account	Ask the holder to sign in with the account they linked
Callback	`unsupported`	This payout cannot be approved in the window	Book a payout the window can fund — see Payouts
Callback	`expired`	The session ran out while the holder was in the window	Create a new session
Callback	`failed`	Anything else	Create a new session and try again

A session that is invalid or already expired when the window opens never reaches your callback: the window shows This link has expired or is invalid and sends nothing back. Give up on the opener side once expiresAt has passed, and close the popup.

Next: Clients

Read the linked client, wait for it to be ready, and keep the one id that identifies it.

Start here

Core concepts

Onboard a client

Move money

Escrow

Ship it

Reference

Changelog

Sign in with HEVN

Before you start

Configure the window

Link an account

2. Create a session on your server

3. Bind the session to this browser

4. Exchange the code

The callback page

Who can be linked

Approve a payout

Verify an individual

Errors

Next: Clients

​Before you start

​Configure the window

​Link an account

​1. Open the popup inside the click

​2. Create a session on your server

​3. Bind the session to this browser

​Sign in with an email you already know

​4. Exchange the code

​The callback page

​Who can be linked

​Approve a payout

​Verify an individual

​Errors

Next: Clients

Before you start

Configure the window

Link an account

1. Open the popup inside the click

2. Create a session on your server

3. Bind the session to this browser

Sign in with an email you already know

4. Exchange the code

The callback page

Who can be linked

Approve a payout

Verify an individual

Errors