When your AI needs to access secure APIs or private data, it needs proper authentication. There are two ways to handle this:

​
1. Dynamic Authentication (Via Widget)

Best for user-specific access where each user has their own credentials. 
// In your frontend app
const options = {
  token: 'YOUR_COPILOT_TOKEN',
  headers: {
    Authorization: 'Bearer ' + userToken,
    'X-Custom-Auth': 'user-specific-key',
  },
};

// React
<WidgetRoot options={options}>
  <Widget />
</WidgetRoot>;

// JavaScript
initOpenScript(options);
Use this when:
  • Users need to be authenticated
  • Each user has different permissions
  • You’re using JWTs or session tokens
  • You need to pass user-specific API keys

​
2. Static Authentication (Via Dashboard)

Best for system-wide credentials that all users share.
1

Open Dashboard

Navigate to your copilot’s settings
2

Add Headers

Under “Global variables/headers”, add your authentication: - API keys - Bearer tokens - Basic auth credentials
Use this when:
  • All users need the same access level
  • You’re using system-wide API keys
  • You don’t want to expose credentials in frontend code
  • You need consistent authentication for all requests

​
Security Best Practices

Widget Headers

  • Never stored on our servers - Used only during request - Perfect for user tokens

Dashboard Headers

  • Encrypted at rest - Stored securely - Best for system credentials

​
Example Use Cases

​
User-Specific Access

// Each user has their own token
const options = {
  headers: {
    Authorization: `Bearer ${userJwtToken}`,
  },
};

​
System-Wide API Access

// Set in dashboard
{
  "X-API-Key": "your-api-key-here"
  "Authorization": "Basic base64-credentials"
}

​
Mixed Authentication

// System API key in dashboard
{
  "X-API-Key": "system-wide-key"
}

// User token in widget
const options = {
  headers: {
    "User-Token": userSpecificToken
  }
};
Security Tips: - Use dashboard authentication for sensitive credentials - Use widget headers for user-specific tokens - Never expose system-wide API keys in frontend code - Always use HTTPS for API calls
Need help? Check our security guide or join our Slack community.