Authentication

The ChatBotKit API provides multiple authentication mechanisms to ensure secure access to resources. Understanding these authentication methods is essential for building reliable integrations and applications.

API Secret Keys

API secret keys are the primary method for authenticating API requests. These keys provide long-lived access to your account and should be treated as sensitive credentials. Secret keys begin with the prefix sk- and are generated through the ChatBotKit dashboard.

To authenticate using an API secret key, include it in the Authorization header of your HTTP requests:

Secret keys provide full access to your account and all associated resources. Store them securely and never expose them in client-side code, public repositories, or logs. Rotate keys regularly and revoke any keys that may have been compromised.

JWT Tokens

JSON Web Tokens (JWTs) provide temporary, scoped access to the API and are ideal for client-side applications or time-limited integrations. JWTs are obtained through the session creation endpoint and contain encoded user information and permissions.

To authenticate using a JWT token:

JWT tokens automatically expire after a predetermined period, enhancing security for temporary access scenarios. They're particularly useful for widget integrations, temporary access grants, and client-side applications where secret keys should not be embedded.

User Impersonation

For parent accounts managing multiple sub-accounts or child users, the API supports user impersonation through special request headers. This allows a parent account to make requests on behalf of child accounts without requiring separate authentication credentials.

Impersonate by User ID

To make requests on behalf of a specific child user, include the X-RunAs-User-ID header:

Impersonate by Email

Alternatively, impersonate a child user by their email address using the X-RunAs-Child-User-Email header:

User impersonation requires that:

• The authenticating account is the parent of the target child account
• The child user relationship was properly established through the sub-accounts system
• The parent account has not been restricted from impersonation capabilities

Authentication Errors

The API returns appropriate HTTP status codes and error messages when authentication fails:

• 401 Unauthorized: Missing, invalid, or expired credentials
• 403 Forbidden: Valid credentials but insufficient permissions for the requested operation

Error responses never expose sensitive information such as whether a particular user exists or details about why authentication failed, preventing information leakage that could aid unauthorized access attempts.

Best Practices

• Secure Storage: Store API keys and tokens in environment variables or secure credential management systems, never in source code
• Key Rotation: Regularly rotate API secret keys and revoke unused keys
• Scoped Access: Use JWT tokens for client-side or time-limited access rather than embedding secret keys
• Monitor Usage: Regularly audit API access logs to detect unusual patterns or unauthorized access attempts
• HTTPS Only: Always use HTTPS for API requests to protect credentials in transit