---
title: Authentication
description: >-
  Comprehensive guide to authenticating with the ChatBotKit API using secret
  keys, JWT tokens, and user impersonation for secure programmatic access.
tags:
  - authentication
  - api-keys
  - jwt
  - authorization
  - security
category: API
index: 1
---
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.

## Running as a Child User

For a parent User managing child Users, the API supports running requests
as a child User through special request headers. This allows the parent User
to make requests on behalf of child Users without requiring
separate authentication credentials.

### Run as a User by ID

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

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

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

### Run as a User by Email

Alternatively, select a child User by its email address using the
`X-RunAs-Child-User-Email` header:

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

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

Running as a child User requires that:
- The authenticating User is the parent of the target child User
- The child User relationship was established through the User API
- The parent User has not been restricted from run-as 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