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

# Botsify API Authentication: Bearer Token, OAuth2, API Key

> Learn how to authenticate Botsify API requests using a Bearer token from the login endpoint, the OAuth2 password grant, or a bot-scoped API key.

Every request to the Botsify API must be authenticated. Botsify supports three authentication methods — Bearer Token, OAuth2 Password Grant, and API Key — each suited to a different integration context. This page explains how each method works, when to use it, and how to include credentials correctly in your requests.

<Info>
  Your `client_id` and `client_secret` are **not** pre-issued static keys. They are returned dynamically in the response body when you call the login endpoint (`POST /api/v1/login`). You must perform a login call first to obtain them before using the OAuth2 Password Grant flow.
</Info>

***

## Method 1: Bearer Token (Recommended for Agentic and MCP Clients)

The Bearer Token method is the simplest and most direct way to authenticate. You exchange your Botsify email and password for a short-lived `access_token`, then include that token in the `Authorization` header of every subsequent API request.

This method is recommended for server-side integrations, agentic clients, and MCP (Model Context Protocol) tooling because the token is easy to pass in a header and works across all API endpoints.

### Step 1 — Obtain an access token

```bash theme={null}
curl -X POST https://app.botsify.com/api/v1/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "yourpassword",
    "agentic-login": true
  }'
```

**Response:**

```json theme={null}
{
  "access_token": "eyJhbGciOiJSUzI1NiJ9...",
  "client_id": "your-client-id",
  "client_secret": "your-client-secret",
  "token_type": "Bearer"
}
```

### Step 2 — Use the token in requests

Pass the token in the `Authorization` header using the `Bearer` scheme:

```bash theme={null}
curl -X POST https://app.botsify.com/api/v1/create-bot \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9..." \
  -d '{
    "bot_name": "Support agent",
    "agent_type": "agent"
  }'
```

***

## Method 2: OAuth2 Password Grant

Botsify supports the OAuth2 Resource Owner Password Credentials Grant (`grant_type=password`). This flow is useful when you are building an application that manages tokens on behalf of your users, or when you need OAuth2-compliant token handling (e.g. automatic refresh logic).

<Info>
  The `client_id` and `client_secret` required by this flow come from the login API response described above in Method 1. Call `POST /api/v1/login` first to retrieve them, then use those values here.
</Info>

### Request

```bash theme={null}
curl -X POST https://app.botsify.com/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "password",
    "client_id": "<FROM_LOGIN_API>",
    "client_secret": "<FROM_LOGIN_API>",
    "username": "you@example.com",
    "password": "yourpassword",
    "scope": ""
  }'
```

**Response:**

```json theme={null}
{
  "access_token": "eyJhbGciOiJSUzI1NiJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}
```

Use the returned `access_token` exactly as described in Method 1 — pass it in the `Authorization: Bearer` header.

***

## Method 3: API Key

Every bot you create has its own **API Key** (also referred to as `apikey` in the API). The API Key is scoped to a single bot and is used primarily for bot-level operations such as sending messages, managing user attributes, and retrieving conversation history for that specific bot.

You can pass the API Key in one of two ways depending on the endpoint:

**As a JSON body field:**

```bash theme={null}
curl -X POST https://app.botsify.com/api/v1/add-user-attribute \
  -H "Content-Type: application/json" \
  -d '{
    "apikey": "YOUR_BOT_API_KEY",
    "messenger_user_id": "user-123",
    "key": "plan",
    "value": "pro"
  }'
```

**As a request header:**

```bash theme={null}
curl -X GET https://app.botsify.com/api/v1/get-users \
  -H "X-Api-Key: YOUR_BOT_API_KEY"
```

<Note>
  The bot API Key is different from your account-level credentials. It is tied to a specific bot and does not grant access to account management endpoints. You can find your bot's API Key in the Botsify dashboard under your bot's settings, or in the response when you create a bot.
</Note>

***

## Keeping Credentials Secure

<Warning>
  Your `access_token`, `client_id`, `client_secret`, and bot API Keys are sensitive credentials. Follow these practices to keep them safe:

  * **Never hard-code credentials** in source code or commit them to version control.
  * **Use environment variables** (e.g. `BOTSIFY_TOKEN`, `BOTSIFY_API_KEY`) to inject credentials at runtime.
  * **Restrict access** to the services and team members that genuinely need each credential.
  * **Rotate credentials** if you suspect they have been exposed.
  * **Do not log full tokens** in application logs or error monitoring tools.
</Warning>

***

## Summary

| Method | Best For | Header / Field |
| - | - | - |
| Bearer Token | Agentic clients, server-side integrations, MCP | `Authorization: Bearer <token>` |
| OAuth2 Password Grant | Applications needing OAuth2-compliant token management | `Authorization: Bearer <token>` |
| API Key | Bot-level operations (messaging, user attributes) | `apikey` in body or `X-Api-Key` header |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.