Chapter 12: Authentication & Security

User authentication, permission management, and resource protection for botserver.

Overview

botserver provides enterprise-grade security with flexible authentication options, granular permissions, and comprehensive rate limiting to prevent abuse.

Initial Setup

When General Bots starts for the first time, it automatically creates an administrator account and displays the credentials in the console. See Initial Setup & Bootstrap for details.

╔════════════════════════════════════════════════════════════╗
║       🤖 GENERAL BOTS - INITIAL SETUP COMPLETE            ║
╠════════════════════════════════════════════════════════════╣
║  Username:             admin                               ║
║  Email:                admin@localhost                     ║
║  Password:             (displayed in console)              ║
╚════════════════════════════════════════════════════════════╝

Important: Save the password shown in your console during first startup. It will not be displayed again.

Authentication Methods

Method	Use Case
Session Token	Web/API access
OAuth2/OIDC	SSO integration via Zitadel
API Key	Service accounts
Bot Auth	Bot-to-bot communication

Quick Start

' Check if user is authenticated
IF user.authenticated THEN
  TALK "Welcome, " + user.name
ELSE
  TALK "Please log in first"
END IF

Security Features

Directory Service: Zitadel handles all user identity management
No Password Storage: Passwords never stored in General Bots
Session Management: Cryptographic tokens, configurable expiry
Rate Limiting: Per-user and global limits with HTTP 429 responses
System Limits: Loop protection, file size limits, resource constraints
Audit Logging: Track all authentication events
Organizations: Multi-tenant support with org-based isolation

Permission Levels

Level	Access
`admin`	Full system access, user management
`org_owner`	Organization management
`bot_owner`	Bot configuration and deployment
`bot_operator`	Bot operation and monitoring
`user`	Standard access
`guest`	Read-only, anonymous chat

Organization Structure

Organization (e.g., "Acme Corp")
├── Users (with roles)
├── Bots (owned by org)
│   ├── sales-bot
│   └── support-bot
└── Drive Storage
    ├── acme-sales-bot.gbai/
    └── acme-support-bot.gbai/

Configuration

name,value
auth-session-ttl,3600
auth-max-attempts,5
auth-lockout-duration,900

Chapter Contents

Initial Setup & Bootstrap - First-time admin setup
User Authentication - Login flows
Password Security - Password policies
API Endpoints - Auth API reference
Bot Authentication - Service accounts
Security Features - Protection mechanisms
Security Policy - Best practices
Compliance Requirements - GDPR, LGPD, HIPAA
Permissions Matrix - Access control
User vs System Context - Execution contexts
System Limits & Rate Limiting - Resource constraints and abuse prevention

Anonymous Chat Access

Anonymous users can use the chat functionality without logging in. The system automatically creates temporary sessions for anonymous users. Authentication is only required for:

User management (Settings)
Bot configuration
Administrative functions
Organization management

4.2 KiB Raw Blame History