Authenticate with the BotSmith API Using Bearer Tokens

BotSmith uses JWT Bearer tokens for API authentication. Obtain a token by registering or logging in, then include it in the Authorization header of every subsequent request.

Never share your access token. Treat it like a password — anyone who has it can make API calls on your behalf.

Public chat endpoints (/api/public/chat/{chatbot_id}) and the public lead endpoint (/api/public/lead/{chatbot_id}) do not require authentication. They are designed for end-users visiting your website through the embedded widget.

Register a New Account

If you don’t have a BotSmith account yet, create one by sending a POST request to /api/auth/register. A successful registration automatically returns an access token so you can start making API calls immediately.

curl -X POST https://app.botsmith.ai/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Smith",
    "email": "you@example.com",
    "password": "yourpassword"
  }'

Request body parameters:

string

required

Your full name.

string

required

Your email address. Must be unique — returns 400 if the address is already registered.

string

required

Your chosen password.

Response (201 Created):

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

string

The JWT token to use in subsequent API requests.

string

Always "bearer".

Log In to Obtain a Token

Send a POST request to /api/auth/login with your email and password:

curl -X POST https://app.botsmith.ai/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "yourpassword"}'

Request body parameters:

string

required

Your registered email address.

string

required

Your account password.

Response (200 OK):

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

string

The JWT token to include in subsequent API requests.

string

Always "bearer".

Using the Token

Include the token as a Bearer value in the Authorization header of every authenticated request:

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  https://app.botsmith.ai/api/chatbots

Replace YOUR_ACCESS_TOKEN with the access_token value returned from the login or register endpoint.

Token Expiry

Tokens expire after a period of inactivity. When your token expires, the API returns a 401 Unauthorized response:

{
  "detail": "Could not validate credentials"
}

When you receive a 401, re-authenticate by calling /api/auth/login again to obtain a fresh token.

Get the Current User Profile

To retrieve the profile of the currently authenticated user, call GET /api/auth/me:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://app.botsmith.ai/api/auth/me

Response (200 OK):

{
  "id": "abc123",
  "name": "Jane Smith",
  "email": "you@example.com",
  "role": "user",
  "status": "active",
  "plan_id": "free",
  "created_at": "2024-03-15T10:00:00Z",
  "last_login": "2024-06-01T09:23:11Z"
}

string

Unique identifier for the user.

string

The user’s display name.

string

The user’s email address.

string

The user’s role: "user" or "admin".

string

Account status: "active", "suspended", or "banned".

string

The user’s current subscription plan identifier (e.g., "free", "starter", "pro").

string

ISO 8601 timestamp of when the account was created.

ISO 8601 timestamp of the most recent login, or null if the user has never logged in.

Log Out

Send a POST request to /api/auth/logout to invalidate the current session. Because BotSmith uses stateless JWT tokens, you should also remove the token from your client storage immediately.

curl -X POST https://app.botsmith.ai/api/auth/logout \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200 OK):

{
  "message": "Successfully logged out"
}

Overview

Endpoints

Authenticate with the BotSmith API Using Bearer Tokens

Register a New Account

Log In to Obtain a Token

Using the Token

Token Expiry

Get the Current User Profile

Log Out

​Register a New Account

​Log In to Obtain a Token

​Using the Token

​Token Expiry

​Get the Current User Profile

​Log Out

Register a New Account

Log In to Obtain a Token

Using the Token

Token Expiry

Get the Current User Profile

Log Out