Identity

Three ways a person reaches Harkly, in order of how much they are trusted.

Public key

init({ publicKey }) alone lets your app say who someone is. That creates and updates the person, records events, and lets them post and vote. It cannot change an existing email, because anyone can read a public key.

Signed token

For email changes and for anything you want to be sure about, sign a JWT on your server with the workspace's SSO secret (Settings → SDK & install):

import { SignJWT } from "jose";

const token = await new SignJWT({ email: user.email, name: user.name })
  .setProtectedHeader({ alg: "HS256" })
  .setSubject(user.id)
  .setIssuedAt()
  .setExpirationTime("1h")
  .sign(new TextEncoder().encode(process.env.HARKLY_SSO_SECRET));

Pass it as identify(user, { jwt }). The secret can be rotated from the dashboard; the rotation is audited.

Anonymous visitors

With init({ anonymous: true }) the SDK keeps a random id in storage before anyone signs in, so a vote cast on the portal is attributed once they do. Off by default: no cookie is set until you say so.

The portal's own sign-in

People who arrive at the portal without your app sign in by email link. They become identified customers with the portal source, and they merge with your identified record the first time your app identifies the same email with a signed token.