​
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
{
  externalId: "user-x123456",
},
{
  headers: {
      'Content-Type': 'application/json',
      'x-api-key': YOUR-MINDSET-API-KEY
  },
}

​
Authorisation Header

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.

  • accountUids (optional, array of accountUid):

You can specify one more Mindset App accounts to automatically add this user to. This to allow embedded agent user sessions to be granted access to restricted agents.

​
Example JSON body

{
  "userEmail": "USER-EMAIL-ADDRESS"
}

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

Please see Best practice: Agent access granted by Account membership

​
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

An authentication token will be generated if a user with the provided email address or externalId exists in your application. If no such user exists, a new user will be created using the provided email address or externalId, and an authentication token will be generated.

The user email must have an email format ( ex :name@company.com). But it does not have to be a real existing email address. The email address can be created dynamically, for example if you want to associate an identifier you could do something like:

usernemail-id12345@gmail.com

​
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 = {
  const 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);
});