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.

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.

---

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

curl -X POST https://app.botsify.com/api/v1/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[e-mail]",
    "password": "yourpassword",
    "agentic-login": true
  }'

Response:

{
  "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:

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

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.

Request

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": "[e-mail]",
    "password": "yourpassword",
    "scope": ""
  }'

Response:

{
  "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:

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:

curl -X GET https://app.botsify.com/api/v1/get-users \
  -H "X-Api-Key: YOUR_BOT_API_KEY"

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.

---

Keeping Credentials Secure

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.

---

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