How can I fix 409 conflict errors with JWT authentication?

Question

Why do I see a 409 conflict error when I authenticate users with JWT authentication in Zendesk messaging?

Answer

With JWT authentication, an external_id is required every time. You can also include a verified email identity. If you include a verified email identity, Sunshine Conversations stores that email as an identity (user.identities), and each identity must be unique. For example, a JWT sign in might create a user with external_id 1234 and the email identity user@example.org.

An email conflict error occurs when the JWT has an external_id and email that do not match what the system already has on record.  For example, if a subsequent JWT contains the external_id 5678 and the verified email identity user@example.org, then the sign in attempt will produce an email conflict error. This is because the given email has already been paired with a different external_id. This mismatch can sometimes occur because a user has changed their email address. If the JWT does not include the email claim, then the conflict would not occur.

You can identify the user that causes the conflict with the List Users API:

API method: GET

https://<subdomain>.zendesk.com/sc/v2/apps/{appId}/users?filter[identities.email]=user@example.org

To resolve the conflict there are two options:

Delete the user in conflict with the Delete User API:

Basic authentication: Use an API key and secret key

Username: API_KEY_ID

Password: API_KEY_SECRET

API method: DELETE

https://<subdomain>.zendesk.com/sc/v2/apps/{appId}/users/{userIdOrExternalId}

Or you can use the Delete User Personal Information API to delete the email identity in conflict:

API method: DELETE

https://<subdomain>.zendesk.com/sc/v2/apps/{appId}/users/{userIdOrExternalId}/personalinformation

In the URLs above, replace {appId} with the ID you receive when you generate the API key and secret key, and replace {userIdOrExternalId} with the previous external_id linked to the user that returns the error.

For more information about the Sunshine Conversations API, see Welcome to the Sunshine Conversations API.

Disclaimer: If you delete the userIdOrExternalId, you wipe the conversation history for the end user after they authenticate with the new external_id and after you delete the user from Sunshine Conversations. This article is for instructional purposes only. Zendesk does not support or guarantee the code. Post any issues in the comments section or search for a solution online.

For more information, see Authenticating end users for messaging.