Authentication

Overview

The Mindset AI SDK 3 uses token-based authentication to link client-side sessions to user accounts within the Mindset AI platform. This authentication mechanism ensures secure, seamless integration of user sessions with your embedded agents. The authentication process handles two scenarios automatically: Existing users: If the user already exists in Mindset AI, the authentication process generates a token that links the current session to their existing account. This provides continuity for returning users. New users: If the user doesn’t exist, the system automatically creates a new user account using the provided identifier (email or external ID) and generates an authentication token. This streamlines onboarding without manual intervention. The authentication token serves as the key to accessing SDK features while maintaining user-specific context, conversation history, and preferences.

Server-Side Only: Authentication must be handled server-side to protect your API key and maintain security. Never expose API keys in client-side code.

How Authentication Works

User initiates session

Your application captures user identification (email or external ID)

Server requests token

Your server makes a secure POST request to Mindset AI’s authentication endpoint with user details

Token generation

Mindset AI validates the request, creates or links the user account, and returns an authentication token

Client-side initialization

Your client-side code uses the token to initialize the SDK and establish the user session

Generate Authentication Token

Make a secure server-side HTTP POST request to the Mindset AI authentication endpoint to generate an authentication token.

Endpoint

POST https://MINDSET-API-HOST/api/v1/appuid/YOUR-APP-UID/sdkusers/auth

Headers

Header	Value	Description
`Content-Type`	`application/json`	Required
`x-api-key`	`YOUR-MINDSET-API-KEY`	Your Mindset AI API key (manage in Developer Tools → API Keys)

API keys are managed in the Agent Management Studio under Developer Tools → API Keys.

Request Body

The request body must include user identification using either externalId or userEmail (not both).

Parameter	Type	Required	Description
`externalId`	String	Conditional*	Unique identifier for the user in your system
`userEmail`	String	Conditional*	Email address of the user
`name`	String	Optional	Display name for the user (used when creating new accounts)
`accountUids`	Array	Optional	Array of Mindset AI account UIDs to grant this user access to restricted agents

*You must provide either externalId OR userEmail, but not both. Requests with neither or both will fail.

Request Examples

Using external ID (recommended):

{
  "name": "John Smith",
  "externalId": "user-x123456"
}

Using email address:

{
  "name": "Jane Doe",
  "userEmail": "[email protected]"
}

With account access:

{
  "externalId": "user-x123456",
  "accountUids": ["account-uid-1", "account-uid-2"]
}

Best practice: Use externalId to control what personally identifiable information (PII) you share with Mindset AI while maintaining user identity across sessions.

Response

On successful authentication, the API returns an authentication token:

{
  "authToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Use this token when initializing the SDK on the client side.

User Management

How User Accounts Work

When you provide a user identifier to Mindset AI:

Lookup: The API checks if a user with that identifier already exists
Create or Link: If the user doesn’t exist, a new account is created and linked to the identifier
Token Generation: An authentication token is generated for this user
Session Continuity: Returning users automatically access their previous conversation threads and context

User Identification Best Practices

Use externalId (recommended):

Gives you strict control over what PII you share with Mindset AI
Allows cross-referencing user activity with your platform
Can be any unique string that identifies the user in your system

Using userEmail:

Email addresses are modified to make them unique to your application
Mindset AI never sends emails to these addresses
The email serves purely as an identification string

Account Membership

The optional accountUids parameter lets you grant users access to restricted agents automatically during authentication. When to use this:

You have agents with restricted access (not public to all users)
You want to control which users can interact with specific agents
You’re implementing role-based or tier-based agent access

For more details, see Agent Access Granted by Agent Sessions.

Server-Side Implementation

Node.js Example

Here’s how to implement authentication in Node.js:

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: 'user-x123456',
  name: 'John Smith' // optional
};

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);
  // Pass this token to your client-side SDK initialization
})
.catch((error) => {
  console.error('Authentication Error:', error);
});

Integration Pattern

Capture user identity in your application (email, user ID, etc.)
Call authentication endpoint from your server with user details
Receive authentication token from Mindset AI
Pass token to client securely (never log or expose it)
Initialize SDK on client side using the token

Security Considerations

API Key Protection

Keep your API key confidential. Store it securely in environment variables or secret management systems. Never expose it in client-side code, version control, or logs.

Best practices:

Store API keys in environment variables
Use secret management services (AWS Secrets Manager, Azure Key Vault, etc.)
Rotate keys periodically
Never commit keys to version control
Use different keys for development and production

Authentication Token Security

Handle tokens securely:

Transmit tokens over HTTPS only
Store tokens securely on the client (memory, secure storage)
Implement token refresh mechanisms for long-lived sessions
Clear tokens when users log out

Never:

Log tokens to console or files
Store tokens in localStorage without encryption
Share tokens between users
Transmit tokens in URL parameters

API Reference

For complete API documentation including error codes, rate limits, and advanced parameters, see the SDK Users API documentation.

Migrate to SDK 3 Authentication

If you’re currently using SDK 2 authentication, you’ll need to migrate to SDK 3’s authentication flow.

Check if you need to migrate: If your code uses the legacy endpoint https://MINDSET-API-HOST/api-authenticate-embedded-user, you need to migrate.

Migration Steps

Generate new API key

In Agent Management Studio, navigate to Developer Tools → API Keys and generate a new API key.

Update authentication endpoint

Replace the legacy endpoint with the new SDK 3 endpoint:

POST https://MINDSET-API-HOST/api/v1/appuid/YOUR-APP-UID/sdkusers/auth

Update request format

Update your request body to use the new parameter format:

{
  "name": "User Name",        // optional
  "externalId": "user-123",   // use either externalId
  "userEmail": "[email protected]"  // or userEmail (not both)
}

Update headers

Use the new API key in the x-api-key header:

{
  "Content-Type": "application/json",
  "x-api-key": "YOUR-MINDSET-API-KEY"
}

Test authentication flow

Verify that your server successfully receives authentication tokens and your client can initialize the SDK.

Key Changes from SDK 2

Aspect	SDK 2 (Legacy)	SDK 3 (Current)
Endpoint	`/api-authenticate-embedded-user`	`/api/v1/appuid/{YOUR-APP-UID}/sdkusers/auth`
API Key Header	Custom format	`x-api-key`
User Identification	Email only	`externalId` or `userEmail`
API Key Management	Legacy system	Developer Tools → API Keys

For complete migration guidance, see the SDK 3 Migration Guide.

Troubleshooting

Authentication request fails with 401

Possible causes:

Invalid or missing API key
API key is from wrong environment (dev key in production)
API key has been revoked

Solution: Verify your API key in Agent Management Studio under Developer Tools → API Keys. Generate a new key if needed.

Authentication request fails with 400

Possible causes:

Missing both externalId and userEmail
Provided both externalId and userEmail
Invalid request body format

Solution: Ensure you provide exactly one user identifier (externalId OR userEmail) in valid JSON format.

Token works initially but fails later

Possible causes:

Token has expired
User account has been disabled
Network connectivity issues

Solution: Implement token refresh logic. Verify the user account is active in Agent Management Studio.

Overview

Integrate Agent Chat SDK 3

Integrate Agent Chat SDK 2

MCP Server Integration

AMS SDK Integration

API Overview

API playground

Webhooks

Overview

How Authentication Works

Generate Authentication Token

Endpoint

Headers

Request Body

Request Examples

Response

User Management

How User Accounts Work

User Identification Best Practices

Account Membership

Server-Side Implementation

Node.js Example

Integration Pattern

Security Considerations

API Key Protection

Authentication Token Security

API Reference

Migrate to SDK 3 Authentication

Migration Steps

Key Changes from SDK 2

Troubleshooting

Authentication request fails with 401

Authentication request fails with 400

Token works initially but fails later

Overview

Integrate Agent Chat SDK 3

Integrate Agent Chat SDK 2

MCP Server Integration

AMS SDK Integration

API Overview

API playground

Webhooks

​Overview

​How Authentication Works

​Generate Authentication Token

​Endpoint

​Headers

​Request Body

​Request Examples

​Response

​User Management

​How User Accounts Work

​User Identification Best Practices

​Account Membership

​Server-Side Implementation

​Node.js Example

​Integration Pattern

​Security Considerations

​API Key Protection

​Authentication Token Security

​API Reference

​Migrate to SDK 3 Authentication

​Migration Steps

​Key Changes from SDK 2

​Troubleshooting

​Authentication request fails with 401

​Authentication request fails with 400

​Token works initially but fails later

Overview

How Authentication Works

Generate Authentication Token

Endpoint

Headers

Request Body

Request Examples

Response

User Management

How User Accounts Work

User Identification Best Practices

Account Membership

Server-Side Implementation

Node.js Example

Integration Pattern

Security Considerations

API Key Protection

Authentication Token Security

API Reference

Migrate to SDK 3 Authentication

Migration Steps

Key Changes from SDK 2

Troubleshooting

Authentication request fails with 401

Authentication request fails with 400

Token works initially but fails later