Identity Verification

Some actions touch personal data — a customer's subscription, their invoices, their order history. Those answers must be tied to a verified person so one visitor can never see another visitor's data. Identity verification lets your already-signed-in users prove who they are to your agent, using a short-lived token your website generates and hands to the widget.

When identity verification is off, your agent still answers general questions normally. It simply will not look up or expose anyone's personal account data — there's no verified person to look it up for.

How It Works

1. You enable identity verification for the chatbot and receive a signing secret that stays on your server.
2. Your server signs a short-lived token for the logged-in user, containing their stable user id and (optionally) their email and name.
3. Your site passes that token to the widget through the embed script.
4. April verifies the token on every message against your secret. If it's valid and unexpired, the visitor is treated as that verified person — and identity-gated actions unlock for them.
5. If there's no token, or it's invalid or expired, the visitor stays unverified and personal-data actions remain disabled.

The raw secret and the token are never sent to the agent's AI and never leave your server-to-April boundary. April only works with the verified identity it resolves from the token.

What It Unlocks

Once a visitor is verified, your agent can safely act on their own account data, such as:

• Billing details — their current plan, subscription status, and invoices
• Personal order history — their past orders, statuses, and tracking

These capabilities stay guarded behind verification. Until a valid token is present for the conversation, the agent will not retrieve or reveal personal account data — even if the visitor asks for it directly.

Setup

Step 1: Turn On Identity Verification

1. Open your chatbot in the April dashboard
2. Go to Integrations in the sidebar
3. Find Identity verification and click Enable identity verification
4. April generates your signing secret and reveals it once — copy it immediately

Your signing secret looks like aprl_sk_…. Treat it like a password: store it as a secret environment variable on your server. It is the only thing that lets your site mint trusted tokens, so it must never appear in client-side code, your repository, or the browser.

If you ever lose it or suspect it leaked, click Rotate secret to issue a new one. Rotating immediately invalidates the old secret, so update your server with the new value right away.

Step 2: Sign a Token on Your Server

When a logged-in user loads a page that shows the widget, sign a short-lived HS256 JWT on your server using your signing secret. Include:

• A stable user id — as external_id (or the standard sub claim). This is how April recognizes the same person across visits.
• email (optional, recommended) — lets the agent match the visitor to their account records.
• name (optional) — used to personalize the conversation.
• exp (required) — a near-term expiry, e.g. 15–60 minutes from now. April rejects tokens with no expiry, expired tokens, and tokens valid more than 24 hours out.

A token payload looks like this:

{
  "external_id": "user_8f31c2",
  "email": "alex@startup.io",
  "name": "Alex Rivera",
  "iat": 1749200000,
  "exp": 1749201800
}

Sign it with the HS256 algorithm and your aprl_sk_… secret. Mint a fresh token per page load (or refresh it before it expires) — short lifetimes keep a leaked token useless almost immediately.

Step 3: Pass the Token to the Widget

Add the signed token to your embed script with the data-identity-token attribute:

<script
  data-chatbot="YOUR_CHATBOT_ID"
  data-identity-token="SIGNED_JWT"
  src="https://theapril.app/widget.js"
></script>

Render this server-side so the token is injected fresh for the logged-in user. For anonymous visitors, omit data-identity-token entirely — the widget still works, just without identity-gated actions.

Step 4: Test It

Load a page where a user is signed in and the token is set, then ask the agent something personal like "What plan am I on?" or "Where's my last order?". The agent should answer using that user's data. Open the same page while signed out (no token) and ask again — the agent should decline to share personal account data.

Example Conversation

Visitor: Can you tell me when my subscription renews?

Agent: You're on the Pro plan, and it renews on June 22, 2026 for $19.99. Your card ending in 4242 will be charged automatically — would you like to update your payment method or view your latest invoice?

Visitor: Just send me the latest invoice please.

Agent: Done — your invoice for May 2026 is ready. Is there anything else I can help you with on your account?

In this conversation the visitor was verified by a valid token, so the agent could safely look up their plan and invoice. Without that token, the same questions would get a polite "I can't access your account details here" response.

Tips

• Keep token lifetimes short. 15–60 minutes is a good balance. The shorter the window, the smaller the impact if a token is ever exposed.
• Use a stable external_id. Use your own permanent user id, not something that changes between sessions, so April recognizes returning customers.
• Never ship the secret to the browser. Sign tokens only on your server. If your secret would ever be visible in client code, rotate it immediately.
• Refresh tokens for long sessions. If a user keeps a tab open past the expiry, mint a new token so identity-gated actions keep working.

FAQ

What happens if a visitor isn't verified? The agent still answers general questions, but it will not retrieve or reveal any personal account data. There's simply no verified person to act on.

Does April ever see my signing secret? Your secret is stored securely and only used server-side to verify tokens. It is never sent to the agent's AI and never exposed in the widget or browser.

What user details should the token include? At minimum a stable user id. Adding the user's email helps the agent match them to their account records, and a name lets it personalize replies. An expiry is always required.

How long is a token valid? As long as you set with its exp claim — we recommend 15–60 minutes. April rejects tokens with no expiry, expired tokens, or tokens valid more than 24 hours into the future.

What if I think my secret leaked? Click Rotate secret to immediately invalidate the old one and generate a new secret, then update your server with the new value.

Can anonymous visitors still use the widget? Yes. Verification only gates personal-data actions. Visitors without a token chat normally — they just can't access account-specific information.