Authenticating end users

Authentication

The Zendesk SDK supports authentication of end users to enable agents to verify their identity within Zendesk. Complete the steps in Authenticating users before beginning the steps below.

You can find a demo app demonstrating the capability of user authentication on our Demo app repository.

LoginUser

To authenticate a user call the loginUser API with your own JWT.

The JWT can contain the following fields:

Name	Type	Mandatory	Comment
external_id	String	Yes	The external id of the user. Required. The maximum length is 255 characters.
name	String	No	The name of the user.
email	String	No	The email of the user.
exp	Integer	No	Integer value of the expiry timestamp, in seconds.

Swift

The result of loginUser can be observed in the optional completionHandler.

Zendesk.instance?.loginUser(with: "your_jwt_here") { result in
    switch result {
    case .success(let user):
        // ...
    case .failure(let error):
        // ...
    }
}

Objective-C

Zendesk *instance = [Zendesk instance];

[instance loginUserWith:@"your_jwt_here" completionHandler:^(ZDKZendeskUser * _Nullable user, NSError * _Nullable error) {
    // ...
}];

LogoutUser

To unauthenticate a user, call the logoutUser API.

This function is intended mainly for authenticated users. However, calling logoutUser for an unauthenticated user clears all associated data, including their conversation history. Note that this data cannot be recovered, so this action should be used only for testing purposes. When the unauthenticated user next accesses the conversation screen, a new user profile and conversation will be created.

Swift

The result of logoutUser can be observed in the optional completionHandler.

Zendesk.instance?.logoutUser { result in
    switch result {
    case .success:
        // ...
    case .failure(let error):
        // ...
    }
}

Objective-C

Zendesk *instance = [Zendesk instance];

[instance logoutUserWithCompletionHandler:^(NSError * _Nullable error) {
  // ...
}];

Note: This will unsubscribe you from push notifications. You will no longer receive these notifications for any of your ongoing conversations. If you log back in and get resubscribed, you will received new notifications but not the ones you missed while you were logged out.

Authentication errors

The most common error that will happen here is a HTTP 401 error or creating a JWT with an expiration timestamp, which leads to an expiration error. In this case a new JWT should be generated and a call made to loginUser.

Authentication lifecycle and authentication expiration

You can create your JWT with an expiration timestamp using the optional exp property. See Creating a JWT token.

Once loginUser is successful, the user remains authenticated until the token expires or an error occurs.

When the token expires, the server will return an expiredJWT error indicating "The JWT has expired". This error can be captured through the authenticationFailed event listener. Following this, the user will lose their access and must re-authenticate using loginUser. If the now unauthenticated user attempts to start a conversation, they will be directed to the conversation screen with an error. The conversation content will not be visible.

Since the SDK doesn't automatically renew the token, you will have to handle the re-authentication process.

Using ZendeskEvent.AuthenticationFailed to reauthenticate the user

You can reauthenticate a user based on the specific error. For example if you wanted to reauthenticate a user once their JWT has expired, you can search for that error in your implementation using the AuthenticationFailed event. Once you are notified that the user's JWT has expired, you can generate a new JWT with a new expiration timestamp and log them back into the SDK.

Swift

Below is a code sample how to reauthenticate a user after their JWT has expired.

Zendesk.instance?.addEventObserver(self) { event in
            switch event {
            case .authenticationFailed(let error as NSError):
                if error.localizedDescription.contains("The JWT has expired") {
                    // generate a new token  newJWTToken
                    DispatchQueue.main.asyncAfter () {
                        Zendesk.instance?.loginUser(with: newJWTToken) { result in
                            if case let.success(response) = result {
                                // Handle login success
                            }
                            else  {
                                // Handle login error
                            }

Authentication merges

When the loginUser API identifies an anonymous user in the Zendesk SDK who already exists in Zendesk (for example, from previous activity on another device), the data from both the anonymous and existing user accounts will be merged. This allows a user to start a conversation anonymously and then log in seamlessly.

For single-conversation, once logged in, the user will see that their previous anonymous conversation has been combined with conversations from their logged-in account, allowing them to continue seamlessly as an authenticated user.

For multi-conversations, once logged in, the user will see that their previous anonymous conversations in the conversation list screen with conversations from their logged-in account, allowing them to continue seamlessly as an authenticated user.

Preventing unwanted authentication merges

If you are using authentication, it's important to authenticate your users prior to displaying the messaging screens. Delaying authentication may result in users engaging in anonymous conversations, complicating their ability to access prior conversations and potentially causing them to create new tickets for existing issues (duplicating tickets).

It is also important to verify that the JWT is not close to expiration when authenticating users before displaying the messaging screens. If the JWT expires while the user is interacting with a conversation, an error must be handled to reauthenticate the user.

For more information and code samples, see Authentication in the Zendesk mobile SDKs.