​
Overview

The Mindset SDK employs an authentication mechanism that uses an authentication token. This token is pivotal in linking the client-side session to a user account within the Mindset platform. The process ensures a seamless integration of user sessions with the platform’s functionalities.

The authentication approach is two-fold:

  • Existing User Linkage: If the user already exists in the Mindset platform, the authentication process will generate a token that links the current client-side session to this existing user account. This facilitates a continuous and integrated experience for returning users.
  • Automatic User Creation: In cases where a user does not exist on the platform, the authentication process automatically triggers the creation of a new user account based on the provided email address. A corresponding authentication token is generated, linking the new user account to the client-side session. This streamlined process ensures new users are smoothly onboarded without additional manual steps.

The authentication token is a critical component in this process, serving as the key to accessing and interacting with the SDK’s features while maintaining user-specific contexts and preferences.

​
Client Authentication Token Generation

A secure server-side HTTP POST request is made to the Mindset authentication SDK Users API endpoint (see the SDK Users API documentation for more details) to generate the {authToken}. This process involves sending user identification details (such as externalId or email address) and your application credentials.

POST https://MINDSET-API-HOST/api/v1/appuid/YOUR-APP-UID/sdkusers/auth
body: {
  userEmail: "myuser@email.com", // Pass the userEmail if you want to authenticate a user by email as you did previously
  // OR
  externalId: "user-x123456", // Pass the externalId if you want to authenticate a user by externalId
},
headers: {
    'Content-Type': 'application/json',
    'x-api-key': YOUR-MINDSET-API-KEY
}

​
Authorisation Header

To authenticate users, you must supply an API key header with your request.

API keys are managed in the app admin UI.

The header should be passed as:

'x-api-key': YOUR-MINDSET-API-KEY

​
Request Body

The body of the request should include:

  • name (optional, String): The friendly name to be set for the user in case of a new user creation.
  • externalId (String): A unique identifier for the user to authenticate.

OR

  • userEmail (String): The email address of the user to authenticate.

​
Example JSON body

{
  "name": "My User Name", 
  "userEmail": "USER-EMAIL-ADDRESS"
}

{
  "name": "My User Name", 
  "externalId": "USER-ID"
}

{
  "userEmail":"USER-EMAIL-ADDRESS",
  "accountUids":["accountUid1", "accountUid2"]}
}

​
Server-Side Authentication

Critical: The authentication process must be handled server-side. This is to ensure the security of your API key and the overall integrity of the user authentication process. Upon successful authentication, the API returns an authentication token. This token is then used in subsequent SDK function calls to authenticate the user.

​
User Handling

When you provide a user identifier to Mindset, our API looks to see if an existing user already exists in our system.

If not, a user is created and linked to the user identifier provided in the external call.

An authentication token is then generated for this user.

We do this so that a returning user will have access to their previous conversation threads with your agent.

We recommend providing user identification using a string in externalId. This allows you to strictly control what PII you share with the Mindset system, but still lets you cross reference user activity with your platform.

If you provide user identification in the form of an email address, then that address will be modified to make it unique to your application before we use it. Mindset never attempts or needs to send emails to this address, so it does not have to exist outside of its use here as an identification string.

​
Security Considerations

API Key Confidentiality: Keep your API key confidential. It should be securely stored and never exposed in client-side code.

​
Authentication Tokens

Handle authentication tokens securely. They should be transmitted and stored using secure methods to prevent unauthorized access.

​
Example Server-Side Usage

// Example Node.js code to make a server-side HTTP POST request for user authentication
// Adapt this example based on your server-side programming environment


const YOUR-MINDSET-API-KEY = 'YOUR-MINDSET-API-KEY' 
const MINDSET-API-HOST = 'MINDSET-API-HOST'
const YOUR-APP-UID = 'YOUR-APP-UID'

const fetch = require('node-fetch');

const requestBody = {
  externalId = "userx123456"
};

fetch('https://${MINDSET-API-HOST}/api/v1/appuid/${YOUR-APP-UID}/sdkusers/auth', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': YOUR-MINDSET-API-KEY
  },
  body: JSON.stringify(requestBody)
})
.then(response => response.json())
.then(data => {
  console.log('Authentication Token:', data.authToken);
})
.catch((error) => {
  console.error('Error:', error);
});

​
Migrate to the new authentication flow

If you are currently using the legacy authentication flow, you will need to migrate to the new one.

You can check you are using the legacy flow by checking if you are using the https://MINDSET-API-HOST/api-authenticate-embedded-user endpoint from your back-end script.

To migrate, you will need to update your server-side code to use the new authentication endpoint and request body format as described below, and you will have to generate a new API KEY using the new API KEYS management system in your Mindset App admin area.

​
STEP 1: Generate a new API Key

In your Mindset App admin area, go to CONFIGURE > API Management section and Generate a key.

Generate a new API Key

​
STEP 2: Update your back-end script

Update your server-side code to use the new authentication endpoint and paste the new API key you have just generated in the x-api-key headers param:

POST https://MINDSET-API-HOST/api/v1/appuid/YOUR-APP-UID/sdkusers/auth
{
  name: "My User Name", // optional 
  userEmail: "myuser@email.com", // Pass the userEmail if you want to authenticate a user by email as you did previously
  // OR
  externalId: "user-x123456", // Pass the externalId if you want to authenticate a user by externalId
  accountUids: ["accountUid1", "accountUid2"] // optional, array of accountUids for agent access granted by account membership
},
{
  headers: {
      'Content-Type': 'application/json',
      'x-api-key': YOUR-MINDSET-API-KEY
  },
}

You can identify the user with either externalId or userEmail. You must provide one of these. Your request will be invalid if you provide neither of them, and also invalid if you provide values for both.

Please see the Back-end section for a full working example.

Please see the SDK Users API documentation for more details on the parameters options.

Please see the Agent access granted by Account membership for more details about the accountUids parameter.