Apex

Signed sign-ins

A sign-in from the browser or an app tells Apex "this visitor is jane@acme.co." Anyone can send that message, so on its own Apex can't tell your real sign-in from someone typing Jane's email into the console. Signed sign-ins let your server vouch for it.

How it works

  1. Apex gives each workspace a sign-in secret. Find it under Settings, Workspace, Signed sign-ins. Only workspace admins can see it.
  2. When someone signs in, your server signs their email with the secret and hands the result (userHash) to the page or app.
  3. The page or app passes userHash to identify(). Apex checks it and attaches the sign-in to the right person.

The secret never leaves your server. The hash only works for that one email.

What Apex does with each sign-in

Sign-inSignature not requiredSignature required
Signed, hash matchesAttached to the personAttached to the person
Signed, hash does not matchHeldHeld
Not signedAttached to the personHeld

A held sign-in never changes a person already in Apex: their devices, traits, and history stay as they were. A new email still becomes a new person, kept out of journeys, partner credit, and scoring until a signed sign-in confirms them. A hash that does not match also shows as an issue on Set up Apex, since it usually means the secret was rotated or the email was changed before signing.

Turn on Require signed sign-ins once every place you call identify() sends a hash.

Sign on your server

The hash is HMAC-SHA256 of the email, lowercased and trimmed, with the secret as the key, written as hex.

import { signSignIn } from "@apex-inc/sdk"; // in your sign-in handler const userHash = await signSignIn(process.env.APEX_SIGN_IN_SECRET, user.email);

Pass it to identify

window.apex.identify(user.email, { name: user.name }, { userHash });

userHash is sent with the sign-in only. It is never saved as a trait.

A signed form submit also counts as a lead for Meta and LinkedIn, even from an app, where there is no website for Apex to check.

Rotating the secret

Rotate from the same settings card if the secret leaks. The old secret stops working immediately, so any sign-in your server signs with it is held until you deploy the new one. If Require signed sign-ins is off, unsigned sign-ins keep working in the meantime.

Apps and app keys

Do not put the sign-in secret, a server key, or a personal key in a mobile app. Use an app key (apex_pk_…, the App key preset under Settings, Organization, API keys) for the app's own traffic, and fetch userHash from your backend at sign-in. An app key lets a sign-up add a new person but never changes someone already in Apex, never counts revenue, and never sends anything to ad platforms.

Next steps

PreviousIdentityNextTransactional · TypeScript