---
title: Authentication
description: Comprehensive guide to authenticating with the ChatBotKit API using secret keys, JWT tokens, and user impersonation for secure programmatic access.
category: API
tags:
  - authentication
  - api-keys
  - jwt
  - authorization
  - security
index: 1
source:
  - lib/session.get.js
---

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:

```http
POST /api/v1/dataset/create
Authorization: Bearer sk-your-secret-key-here
Content-Type: application/json

{
  "name": "My Dataset",
  "description": "Customer support knowledge base"
}
```

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:

```http
GET /api/v1/bot/list
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

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:

```http
POST /api/v1/bot/create
Authorization: Bearer sk-parent-account-key
X-RunAs-User-ID: child-user-id-here
Content-Type: application/json

{
  "name": "Child Account Bot"
}
```

### Impersonate by Email

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

```http
POST /api/v1/dataset/create
Authorization: Bearer sk-parent-account-key
X-RunAs-Child-User-Email: child@example.com
Content-Type: application/json

{
  "name": "Child Account Dataset"
}
```

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