Identity verification
Available on every plan.
ORKA_SESSION and Orka.update() run in the browser. Anyone can open the console and claim to be [email protected]. Your team would then see a conversation that looks like it comes from that customer.
Identity verification closes that door. Your back end signs the email of the logged-in user with a secret only your server and Orka know. Orka checks the signature, and shows a green check next to the email, in the inbox and on the contact page. A forged email has no valid signature.
How it works
- Your back end computes
HMAC-SHA256(secret, email)for the logged-in user. - Your page gives the email and the signature to the SDK.
- Orka recomputes the signature. If it matches, the email is verified.
The secret never reaches the browser. The signature is only valid for that one email.
Set it up
1. Get your secret
In the dashboard: Settings → Developers → Identity verification → Generate secret. The secret is per project, and shown once. Keep it on your server, like a password. Owners and admins of the project can generate it.
Generating the secret changes nothing for your visitors: until your pages send signatures, emails are accepted as before, unverified.
2. Sign the email on your back end
The email is signed lowercased and trimmed. The signature is the hex digest.
// Node.js
import crypto from "crypto";
const signature = crypto.createHmac("sha256", process.env.ORKA_IDENTITY_SECRET).update(user.email.trim().toLowerCase()).digest("hex");
# Python
import hmac, hashlib, os
signature = hmac.new(
os.environ["ORKA_IDENTITY_SECRET"].encode(),
user.email.strip().lower().encode(),
hashlib.sha256,
).hexdigest()
// PHP
$signature = hash_hmac("sha256", strtolower(trim($user->email)), getenv("ORKA_IDENTITY_SECRET"));
# Ruby
signature = OpenSSL::HMAC.hexdigest("sha256", ENV["ORKA_IDENTITY_SECRET"], user.email.strip.downcase)
Check your code with this test vector:
| Input | Value |
|---|---|
| Secret | 5d2f0c7a9b3e4f61a8c0d9e2b7f41c36e0a95d18c3b24f7e96a1d0c8b5e37f42 |
[email protected] |
|
| Signature | 9589dba9033cb4700cac259232e6fc303b1ce55ba31bad3854309d0a54f7d6a1 |
3. Give both to the SDK
<script type="text/javascript">
window.ORKA_SESSION = {
email: "[email protected]",
signature: "SIGNATURE_FROM_YOUR_BACK_END",
name: "Ada Lovelace",
};
</script>
Or later, for instance after a login in a single page application:
window.Orka.update({ email: user.email, signature: user.orkaSignature, name: user.name });
4. What your team sees
| Email comes from… | In the inbox |
|---|---|
| The SDK, valid signature | Green check |
| The SDK, no signature or a wrong one | Accepted, no check |
| The visitor typing their email in the chat | Accepted, no check |
Nothing is refused: an email without a valid signature is kept, it is simply not verified. Tell your team what the check means. Without it, the email was claimed by the person in the chat, not confirmed by your product: ask for more before acting on a sensitive request.
What a verified email unlocks
- The green check next to the email, in the inbox and on the contact page.
- The
email_verifiedfield in the REST API and in webhooks, on the visitor of a conversation and on contacts. Check it before your automations act on a request ("cancel my subscription"). - Session continuity, which relies on it.
The check is per browser session. If someone types the email of a verified contact in the chat, their conversation shows the email without the check: visitor.email_verified is false, even though contact.email_verified is true. Look at the visitor.
For the same reason the check goes away when the email of the visitor is changed by someone else than their browser: an agent in the dashboard, or PATCH /conversations/{id}/visitor. Writing the same email again keeps it.
Contacts your back end writes through the REST API (POST /contacts, POST /events) are verified: your server knows its users.
Rotate the secret
Settings → Developers → Identity verification → Rotate secret. The old secret stays valid for 24 hours, so you can deploy the new one without an unverified gap.
Turn identity verification off deletes the secret: no new email is verified. Emails verified before keep their check.
Troubleshooting
- The check does not show. Compare your output with the test vector. The usual causes: the email was not lowercased, the digest is base64 instead of hex, or the secret of another project was used.
- It works for some users only. Look for spaces or capitals in the emails of your database.
- The signature is computed in the browser. Then the secret is public. Rotate it, and move the code to your server.
- It works after a reload only.
Orka.update()calls are sent after 3 seconds. The check appears once the email and the signature reached Orka.