⚠️ This feature is in beta. To be added, reach out to security@intercom.io
If you have the Messenger installed on your site for logged in users, it's essential to secure it and prevent bad actors from impersonating your users or sending unauthorized data.
To improve security and flexibility for our customers, we introduce JSON Web Tokens (JWTs) as a more secure and scalable way to authenticate users in Messenger.
If you’re currently using Identity Verification (IDV) to verify users, switching to JWTs will give you:
Greater control over authentication – Manage session expiry and revocation yourself, rather than relying on fixed configurations.
Stronger security – JWTs allow for time-limited, signed tokens, reducing the risk of replay attacks.
Improved data security – Define exactly which user attributes can be updated, reducing exposure of sensitive data.
Future-proofing – JWTs are the recommended replacement for IDV, ensuring your authentication system stays aligned with best practices.
Who should migrate?
This migration is relevant for all customers currently using IDV, especially if you:
✅ Need better control over session expiry and token revocation
✅ Want to enforce secure, user-specific attribute updates
✅ Handle sensitive customer data and require stronger authentication
✅ Are planning for long-term security improvements in your workspace
While IDV will continue to work for now, JWTs offer a more modern, secure approach that aligns with best practices for authentication. This guide will walk you through the migration process step by step.
Key differences between Identity Verification and Messenger Security with JWTs
| Identity Verification | Messenger Security with JWTs |
Verification method | HMAC-SHA256 signed hash | JWT signed token |
Supports expiry? | No | Yes |
Support secure data updates? | No | Yes |
Recommended for | Basic identity verification in the Messenger | Secure authentication with better session control and secure data handling |
Migration steps
⚠️ This feature is in beta. To be added, reach out to security@intercom.io
Step 1: Update your integration to generate JWTs instead of hashes
Stop generating HMAC-SHA256 signatures for Identity Verification.
Generate a new secret key for your Messenger, choosing which platforms you wish for it to apply to
Instead, generate a JWT using your secret key.
Here's a sample server-side code configuration for Node.js:
const jwt = require("jsonwebtoken");
const payload = {
user_id: "USER_ID_HERE", // Required
email: "EMAIL_ADDRESS_HERE", // Optional
data_attribute: "YOUR_DATA", // Optional
exp: Math.floor(Date.now() / 1000) + 3600 // Expires in 1hr
};
const secret = process.env.MESSENGER_SECRET_KEY || "YOUR_MESSENGER_SECRET_KEY"; // Secure key storage
const intercomUserJwt = jwt.sign(payload, secret, { algorithm: "HS256" });What to put in your JWT payload:
user_idto identify the user. This is a required field.An optional timestamp (
exp) for expiryAny other data attributes you wish to send securely for your users
For detailed instructions on how to generate JWTs for your workspace see our main help centre doc or your security settings.
Step 1a: A note about data attributes
If you are currently sending data attributes about your users through the Messenger, you should update your integration to send those attributes securely within your user JWT. To do this, add any attributes to your payload and ensure that any insecure Messenger requests are blocked.
In the code example above, our payload signs the user_id and email. It also includes an expiry, which should also go into the payload.
For these attributes, we should now disable insecure Messenger updates for those attributes. This means that that can only updated via a valid JWT and never without.
We recommend you enable this toggle for any attribute you’re sending in your JWT. You can look at your workspace’s attributes under Settings > Data > People
Note: This attribute updates toggle does not prevent you from collecting data directly from leads with a bot. This data comes directly from the user.
Step 2: Update your frontend snippet to send JWTs for users
Instead of passing an HMAC signature for IDV, pass the JWT in Messenger settings as intercom_user_jwt
For Web (JavaScript SDK):
window.Intercom("boot", {
api_base: "https://api-iam.intercom.io",
app_id: "<YOUR_APP_ID_HERE",
intercom_user_jwt: "<YOUR_USER_JWT_HERE>"
};
As noted in the previous section above, we are now sending our data attributes within the JWT and they have been removed from the snippet.
For detailed instructions on how to generate JWTs for your workspace see our help centre doc or your security settings.
Mobile (iOS/Android SDKs): JWTs are not supported on the mobile SDKs just yet. Here you should continue to use Identity Verification for now.
Troubleshooting
There are verbose failure logs and a token debugger tools in your security settings to help with moving to JWTs.
For more information see our installation guide here.
Common Questions
What happens if I don’t migrate?
Identity Verification will continue working for now, but JWTs provide stronger security and better control.How do I revoke a JWT session?
You can set a short expiry (exp) or rotate signing keys to invalidate old tokens.Can I use both Identity Verification and JWTs together?
Once JWT authentication is enabled for a platform, Identity Verification is no longer needed. However, you can use JWTs and Identity Verification independently on web, iOS and Android as these are all set up individually.
Need more help? Get support from our Community Forum
Find answers and get help from Intercom Support and Community Experts