> ## Documentation Index
> Fetch the complete documentation index at: https://document.botsmith.pro/llms.txt
> Use this file to discover all available pages before exploring further.

# Authenticate with the BotSmith API Using Bearer Tokens

> Learn how to register, obtain your BotSmith API token by signing in, and how to include it as a Bearer token in every API request.

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.

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

<Warning>
  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.
</Warning>

## 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.

```bash theme={null}
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:**

<ParamField body="name" type="string" required>
  Your full name.
</ParamField>

<ParamField body="email" type="string" required>
  Your email address. Must be unique — returns `400` if the address is already registered.
</ParamField>

<ParamField body="password" type="string" required>
  Your chosen password.
</ParamField>

**Response (`201 Created`):**

```json theme={null}
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}
```

<ResponseField name="access_token" type="string">
  The JWT token to use in subsequent API requests.
</ResponseField>

<ResponseField name="token_type" type="string">
  Always `"bearer"`.
</ResponseField>

***

## Log In to Obtain a Token

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

```bash theme={null}
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:**

<ParamField body="email" type="string" required>
  Your registered email address.
</ParamField>

<ParamField body="password" type="string" required>
  Your account password.
</ParamField>

**Response (`200 OK`):**

```json theme={null}
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}
```

<ResponseField name="access_token" type="string">
  The JWT token to include in subsequent API requests.
</ResponseField>

<ResponseField name="token_type" type="string">
  Always `"bearer"`.
</ResponseField>

***

## Using the Token

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

```bash theme={null}
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:

```json theme={null}
{
  "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`:

```bash theme={null}
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://app.botsmith.ai/api/auth/me
```

**Response (`200 OK`):**

```json theme={null}
{
  "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"
}
```

<ResponseField name="id" type="string">
  Unique identifier for the user.
</ResponseField>

<ResponseField name="name" type="string">
  The user's display name.
</ResponseField>

<ResponseField name="email" type="string">
  The user's email address.
</ResponseField>

<ResponseField name="role" type="string">
  The user's role: `"user"` or `"admin"`.
</ResponseField>

<ResponseField name="status" type="string">
  Account status: `"active"`, `"suspended"`, or `"banned"`.
</ResponseField>

<ResponseField name="plan_id" type="string">
  The user's current subscription plan identifier (e.g., `"free"`, `"starter"`, `"pro"`).
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp of when the account was created.
</ResponseField>

<ResponseField name="last_login" type="string | null">
  ISO 8601 timestamp of the most recent login, or `null` if the user has never logged in.
</ResponseField>

***

## 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.

```bash theme={null}
curl -X POST https://app.botsmith.ai/api/auth/logout \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Response (`200 OK`):**

```json theme={null}
{
  "message": "Successfully logged out"
}
```