Documentation | BotEsq

Authentication

Learn how to authenticate your AI agents with BotEsq using API keys and session tokens.

Overview

BotEsq uses a two-step authentication process:

API Key - Used to identify your operator account and start sessions
Session Token - Short-lived token used for all subsequent API calls

API Keys

API keys are long-lived credentials that identify your operator account. They are used only for starting sessions.

Key Format

text

botesq_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
botesq_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

botesq_live_ - Production API keys
botesq_test_ - Test/sandbox API keys (no real charges)

Security Warning

Never expose your API keys in client-side code, public repositories, or logs. Treat them like passwords.

Session Tokens

Session tokens are short-lived credentials created by the start_session tool. They are used for all subsequent API calls.

typescript

const session = await mcp.callTool("start_session", {
  api_key: process.env.BOTESQ_API_KEY,
  agent_identifier: "my-legal-assistant-v1"
});
 
// Store the session token for subsequent calls
const sessionToken = session.session_token;

Session Properties

Property	Value
Expiration	24 hours after last activity
Renewal	Automatic on each API call
Format	`sess_xxxxxxxx...`
Scope	Single agent instance

Environment Variables

We recommend storing your API key in an environment variable:

.env

# BotEsq API Configuration
BOTESQ_API_KEY=botesq_live_your_api_key_here
 
# Optional: Override the default server URL
BOTESQ_SERVER_URL=https://api.botesq.com

Session Management

Best practices for managing sessions in your application:

typescript

class BotEsqClient {
  private sessionToken: string | null = null;
  private sessionExpiry: Date | null = null;
 
  async ensureSession(): Promise<string> {
    // Check if we have a valid session
    if (this.sessionToken && this.sessionExpiry && this.sessionExpiry > new Date()) {
      return this.sessionToken;
    }
 
    // Start a new session
    const session = await this.mcp.callTool("start_session", {
      api_key: process.env.BOTESQ_API_KEY,
      agent_identifier: "my-agent"
    });
 
    this.sessionToken = session.session_token;
    // Sessions last 24 hours, but refresh on activity
    this.sessionExpiry = new Date(Date.now() + 23 * 60 * 60 * 1000);
 
    return this.sessionToken;
  }
 
  async askQuestion(question: string): Promise<string> {
    const token = await this.ensureSession();
 
    const result = await this.mcp.callTool("ask_legal_question", {
      session_token: token,
      question
    });
 
    return result.answer;
  }
}

Authentication Errors

Handle these common authentication errors:

Error Code	Description	Resolution
INVALID_API_KEY	API key is malformed or revoked	Check your API key in the dashboard
SESSION_EXPIRED	Session token has expired	Call start_session again
INVALID_SESSION	Session token is invalid	Call start_session again
RATE_LIMITED	Too many requests	Implement exponential backoff