To improve security and flexibility for our customers, we introduced 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

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_id to identify the user. This is a required field.
An optional timestamp (exp) for expiry
Any 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.

Note: If you are currently sending data attributes about your users through the Zendesk or Fin 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.

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 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.

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 Settings > Messenger > Security to help with moving to JWTs.

For more information see our installation guide here.

FAQs

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, 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.

Migrating from Identity Verification to Messenger Security with JWTs