App Key and Identity Secret

Every Convot app has two identifiers: an app key and an identity secret. They serve different purposes and have different security requirements.

App key

The app key (formatted like app_3f9c…) is the identifier you put in the embed snippet:

<script>
  window.Convot = { app_id: "app_YOUR_KEY_HERE" };
</script>

The app key is public. It is safe to include in client-side code, commit to your repository, and expose in your HTML source. Anyone can see it, and that is fine - it only tells Convot which account to load, not who has permission to do anything.

Find your app key under Settings → Apps → [your app] → Setup in the “App key” card.

Identity secret

The identity secret is a long random string used to sign Convot.identify calls so Convot can verify that the visitor claiming to be [email protected] really is who they say they are.

Why it matters

Without verification, any visitor could call:

Convot.identify({ email: "[email protected]" });

and Convot would attach their session to that contact. The identity secret prevents this.

How to sign an identify call

On your server, compute an HMAC-SHA256 of the user’s external_id (or email if you send no external_id) using the identity secret as the key:

# Ruby
require "openssl"
user_hash = OpenSSL::HMAC.hexdigest("SHA256", ENV["CONVOT_IDENTITY_SECRET"], external_id)

// Node.js
const crypto = require("crypto");
const userHash = crypto
  .createHmac("sha256", process.env.CONVOT_IDENTITY_SECRET)
  .update(externalId)
  .digest("hex");

Then pass user_hash in the identify call in your client-side code:

Convot.identify({
  email: "[email protected]",
  external_id: "your_user_id_123",
  name: "Jane Doe",
  company: "Acme Inc",
  phone: "+1234567890",
  avatar_url: "https://example.com/jane.png",
  user_hash: "SERVER_GENERATED_HASH",
  custom_data: {            // any key-value pairs you want on the contact
    plan: "pro",
    shopify_store: "acme.myshopify.com",
    order_count: 42
  }
});

All identify fields

Enforcing verification

On the Setup page there is a Require verification checkbox. When on, Convot rejects any identify call that does not include a valid user_hash.

Rotating the secret

If your identity secret is compromised, click Rotate on the Setup page. A new secret is generated immediately. Any server still signing with the old secret will fail verification until you update it.

Summary

Next steps

• Verifying your install
• Install on a Shopify app for Shopify-specific identify patterns.