Understanding and setting up user authentication for messaging


When you provide conversational support, users might try to carry on a conversation across multiple devices and channels. By authenticating end users, you can make sure all points of contact are associated with the correct end user. This can enhance the quality of support your agents provide and increase the security of sensitive information that might come up while agents assist your end users.


What's my plan?







All Suites

Team, Growth, Professional, Enterprise, or Enterprise Plus









When you provide conversational support, users might try to carry on a conversation across
multiple devices and channels. By authenticating end users, you can make sure all points
of contact are associated with the correct end user. This can enhance the quality of
support your agents provide and increase the security of sensitive information that
might come up while agents assist your end users.
This article contains the following topics:
Terminology for messaging authentication
Overview of implementing messaging authentication for end users
Creating and sharing a signing key
Authenticating end users with only an external ID
Incorporating email identities into your user authentication
Resolving conflicts between external IDs and emails in JWTs


Related article:
About the user experience for messaging user
authentication




Terminology for messaging authentication

In addition to understanding the user and agent experience with messaging
authentication, it's important to understand the following terminology when
implementing messaging authentication:

JWT: Zendesk uses signed JSON Web Tokens (JWTs) to authenticate end
users for messaging. These tokens contain details that verify the identity
of the end users. For more information about JWT, see jwt.io.

Signing key: A signing key is created by a Zendesk admin in Admin
Center and shared with a developer on your team, who then uses it to sign
the JWT as necessary.

External ID: An alphanumeric string, such as an ID from an external
system, that is unique to each user. This is the primary identification for
messaging authentication, even when an email address is included in the
JWT.

User name: (Optional) The name of the end user associated with the
external ID or email address. If you include the user's name in the JWT, it
appears in the Agent Workspace. This information can help agents communicate
with end users.

Email: (Optional) The unique email address associated with an end
user.





Considerations for authenticating end users for messaging

Consider the following information before authenticating end users for messaging
If you configure the Web Widget to use help center authentication, the user's
messaging interactions in the Web Widget automatically adopt the user's logged-in
identity, and the user's name and email can be shared with bots and agents that
engage with the user. However, before you can use this feature, you must turn on help center authentication.
Also consider the following limitations for messaging authentication for users:


End-user authentication for messaging is available for the Web Widget and
mobile SDK channels only.
When using multi-conversation messaging,
users can be marked as authenticated on a maximum of 100 active tickets (any
status other than Solved or Closed) concurrently.





Overview of implementing messaging authentication for end users

Zendesk uses JSON Web Tokens (JWTs) to authenticate messaging end users, which
provides a flexible and stateless way to verify user identities and secure API
endpoints.

Implementing end-user authentication for messaging requires collaboration between
admins and a developer on your team.
The process of messaging authentication begins with an admin generating a
signing key and providing it to a developer. Then the developer uses the
signing key to implement a back-end service that can create signed JWTs for
users as requested.
When requested, the back-end service creates and returns signed JWTs to your
website or mobile app. The JWTs created by this service must include a
unique external ID and, optionally, an email address to identify the end
user.
Anytime the user is logged in, your website or app needs to call an
equivalent login API available for Web Widget
and mobile SDKs, at which time the JWT is passed to Zendesk to verify the
claimed identity of the user.


Note: Optionally, you can turn on help center authentication to
automatically associate user identities with end users logged in to the help
center.

For more information, particularly for the developers on your team, see Enabling authenticated visitors for messaging
with Zendesk SDKs or watch the following video:

Authenticating end users in web messaging (17:22)



Creating and sharing a signing key

Signing keys are used by developers to create JWTs for end users. You must be an
admin to create a signing key. You can create a maximum of 10 keys. If you attempt
to create a new key after reaching your limit of 10, you are prompted to delete
unused keys.

To create and share a signing key
In Admin Center, click
Account in the sidebar, then select Security > End user
authentication.
Click the Messaging tab, then click Create key. If you are
creating your first key, Create key appears at the bottom of the
page. Otherwise, it appears in the top-right corner.

Enter a Name for the key and click Next.
When prompted, click Copy to copy the shared secret. The key is
saved and an ID is automatically assigned. You can find a key's ID in
the list of keys on the Messaging tab of the End user authentication
page.

Confidentially send the key's ID and the shared secret you copied to your
developer.
Click Hide key forever.





Authenticating end users with only an external ID

To authenticate an end user, you must supply an external ID in the JWTs you issue to
users. Zendesk uses the external ID provided in a JWT as the primary identifier for
user authentication for messaging. When performing the user authentication, Zendesk
first resolves an existing user with the external ID. If an email address is included in the
JWT, it is used to resolve user identity only when no existing users match the
external ID.


Signing JWTs with an external ID only

After an admin creates a signing key, the developer on your team can use it to
create a service that generates JWTs for end users. When your developer creates
JWTs using an external ID, the JWT payload needs to include the following
information:

external_id: (Required) This is the unique alphanumeric string that can be used to
identify each user. See Selecting the external ID to use in JWTs issued
to users.

scope: (Required) The caller's scope of access. The only valid value is user.

name: (Optional) The name of the user. Including the name in the JWT payload allows
Zendesk to display the user's name in the Agent Workspace and helps your agents
provide more customized support.


For example:
{
"external_id": "12345678",
"scope": "user",
"name": "Jane Soap"
}




Selecting the external ID to use in JWTs issued to users

Consider the following requirements and expectations when deciding what to use as
external IDs in the JWTs you issue to users:
An external ID must be an alphanumeric string.
External IDs can be a maximum of 255 characters.
Each user's external ID must be globally unique at the account level.
If your account has multiple brands, external IDs must be unique
across all brands.

A user's external ID should never change.
A user can have only one external ID assigned to them.


Some examples of good choices for external IDs include: an incremented or
randomized ID assigned at initial contact (example: usr_12345) or, for multiple
brands, a brand-specific identifier combined with an incremented or randomized
ID assigned (example: brand1_a8dedg).
Avoid using the user's email address and phone number because these can change
over time and users can have multiple values. Also avoid the user's name, since
this may not be unique.




Incorporating email identities into your user authentication

In addition to the external ID, you can choose to use email identities with
authenticated users, unauthenticated users, or both:
Authenticated users are authenticated through signed JWTs. The use of
JWTs provides a trustworthy approach because the content of a signed JWT
can't be tampered with by end users. If you're concerned about
impersonation attacks, you should restrict email identities to
authenticated end users. This is the most secure option and is the
default configuration for new Zendesk accounts.

Unauthenticated users are end users who provide an email address in response
to a prompt by a Zendesk bot. Keep in mind that permitting the use of
email identities for unauthenticated users can make you vulnerable to
people impersonating other users by providing an email address they
don't own.




Tip: Check out Thomas Verschoren's blog post Messaging authentication: Verified email and
merging existing users based on email, where the flow chart contributed
below originally appeared.
The following flow chart demonstrates how email identities can be used in your
messaging authentication:

View full size



Configuring email identities

With the Web Widget or mobile apps, users can provide their email address in
response to a form or AI agent prompt. In these scenarios, there's nothing
preventing a malicious user from providing someone else's email address in an
attempt to impersonate them. However, using JWTs to authenticate users with both
external IDs and email identities is a more trustworthy way to assign email
addresses to users.
Depending on your settings, agents could see both form-collected and JWT-provided
email addresses in user profiles. On new Zendesk accounts, email identities are
turned on and configured to use only verified email addresses. This is the most
secure option. Older accounts are configured to use both verified and unverified
email addresses.

To turn on email identities
In Admin Center, click
Channels in the sidebar, then select Messaging and social >
Messaging.
Click Manage settings.
Click Email identities, and then select one of the following
options:

Use only
verified emails: (Default) Email identities
are created only for users who are authenticated and have a
verified email address included in their issued JWT.

Use both
verified and unverified emails: In addition
to the email identities for authenticated users with verified
email addresses being visible in user profiles, unverified email
addresses provided by users through AI agent flows are also
added to the user's profile.


(Not recommended) If you want any user, even unauthenticated users, to
be able to claim verified email addresses, select Unauthenticated user can
claim verified emails.
Click Save settings.




Using only verified emails

Email identities are created only for users who are authenticated and have a
verified email address included in
their issued JWT.
With this option, agents see the email address provided by unauthenticated
end users in the conversation history, but they won't see an email identity
attached to the user. If an agent needs to follow up with an unauthenticated
user over email, they must manually add the email identity to that user
record.

Note: Prior to manually adding an email identity or merging two user records, we
recommend having your agents perform an identity verification check to
prevent social engineering attacks.



Using both verified and unverified emails

In addition to the email identities for authenticated users with verified
email addresses being visible in user profiles, unverified email addresses
provided by users through AI agent flows are also added to the user's
profile.
This option is less secure because malicious users could still attempt
impersonation attacks. However, agents can inspect the user profiles to
determine whether an email address is verified. Unverified email addresses
are clearly marked in the Agent Workspace. When agents need to send email
follow-ups, they can be instructed to verify end users with security
questions to increase confidence that the end user is who they say they
are.
In the event of a conflict, verified email identities supersede unverified
email identities. This prevents imposters from squatting on unverified email
addresses. For example, if an unauthenticated user provides an email address
that is later provided by an authenticated user in a JWT as a verified email
address, the email identity goes to the verified email.





Event order
Event
Resulting email identity




1
An unauthenticated user provides a form-collected email.
For example, alice@example.org

Zendesk creates a new, unauthenticated user (id: 12345)
with the unverified email identity
(alice@example.org).


2
An authenticated user is issued a JWT with the following
claims:
external_id: 1A23B

email: alice@example.org

email_verified: true



Zendesk creates a new, authenticated user (id: 22345) with
a verified email identity (alice@example.org). The
unauthenticated user (id: 12345) loses its unverified email
identity because it was superseded by a verified
identity.








Allowing unauthenticated users to claim verified emails (not recommended)

In contrast to the other email identity options, this setting allows users to
assume the identity of authenticated users simply by providing that user's
email address when prompted. When selected, verified emails don't supersede
unverified emails.
This option is the least secure and most susceptible to impersonation
attacks. However, diligent agents can still detect potential imposters in
this scenario by looking for the green check mark icon on the user's profile
and next to their messages, which indicates whether the user is
authenticated.
When you select this option, the verification state of email identities
collected from messaging channels is no longer trustworthy because an
imposter can show up after a user is authenticated and take possession of
their email status in a later messaging interaction. This means
impersonation attacks are more likely to succeed and agents have limited
means of knowing whether the end user is who they claim to be. However,
verified email identities still supersede unverified email identities and
the email identity is removed from the imposter's user record.




Issuing JWTs with email addresses

If you're using email identities, you must include two additional claims in the
JWTs you issue to end
users. That means your JWTs will include the following fields:

external_id: (Required) This is the unique alphanumeric string that can be used to
identify each user. See Selecting the external ID to use in JWTs issued
to users.

scope: (Required) The caller's scope of access. The only valid value is user.

name: (Optional) The name of the user. Including the name in the JWT payload allows
Zendesk to display the user's name in the Agent Workspace and helps your agents
provide more customized support.



email: (Required) The email address of the user being signed in.
Must be unique to the user. Set the email address to the user's
primary email address in Agent Workspace. The inclusion of secondary
email addresses in JWTs isn't supported.


email_verified: (Optional) Whether the end user in question has
proven ownership of the email address. If you want end users to have
verified email identities, the JWTs you issue must contain both
email and "email_verified": true
claims.


For example:
{
"external_id": "12345678",
"email": "janes@soap.com",
"email_verified": true,
"name": "Jane Soap",
"scope": "user"
}





Resolving conflicts between external IDs and emails in JWTs

Zendesk uses the external ID as the primary identifier, with email addresses being
used only if no matches are found for the external ID.
It's best to implement messaging authentication with conflict-avoidance in mind. For
example, pick your external IDs and email settings in Zendesk to ensure they can't
conflict. If, however, an email address presented in a JWT is already associated
with a different external ID, Zendesk rejects the JWT and the end user's login
attempt fails. When this happens, the conversation begins with the user in an
unauthenticated state.


Note: When an unauthenticated user on the Web Widget or Mobile SDK authenticates,
and the authenticated user already exists (if they were previously active on a
different device, for example) a user merge will occur. See Merging because of a login event in
our developer documentation.


To resolve conflicts between external IDs and emails in JWTs
Update the JWT to use a different external_id value or
email address. OR

Delete the user with the conflicting external_id, freeing
it up to be used by a different end user. See Delete User in the Sunshine Conversations
API.




{
"@context": "https://schema.org",
"@type": "TechArticle",
"@id": "https://support.zendesk.com/hc/en-us/articles/4411666638746",
"url": "https://support.zendesk.com/hc/en-us/articles/4411666638746",
"headline": "Understanding and setting up user authentication for messaging",
"description": "You can set up user authentication for messaging by using signed JSON Web Tokens (JWTs) with unique external IDs and optional email identities to verify end user identities and secure messaging interactions across devices and channels.",
"articleSection": "Web Widget documentation",
"datePublished": "2021-11-22T16:25:27+00:00",
"dateModified": "2026-04-29T21:33:55.421504+00:00",
"inLanguage": "en-US",
"mainEntityOfPage": {
"@type": "WebPage",
"@id": "https://support.zendesk.com/hc/en-us/articles/4411666638746"
},
"author": {
"@type": "Organization",
"name": "Zendesk",
"@id": "https://www.zendesk.com"
},
"publisher": {
"@type": "Organization",
"name": "Zendesk",
"@id": "https://www.zendesk.com"
},
"isPartOf": {
"@type": "WebSite",
"name": "Zendesk Help",
"@id": "https://support.zendesk.com/hc/"
},
"about": {
"@type": "SoftwareApplication",
"name": "Zendesk",
"@id": "https://www.zendesk.com"
}
}
