Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.praison.ai/llms.txt

Use this file to discover all available pages before exploring further.

API servers generated by praisonai deploy run --type api require bearer token authentication by default as of PraisonAI 4.6.34.

​
Quick Start

1

Default (auth on)

Start the API server and capture the auto-generated token from stderr:
praisonai deploy run --type api
# Look for output like:
# [praisonai-api] generated API token: abc123def456ghi789...
Then make authenticated requests:
curl -H "Authorization: Bearer abc123def456ghi789..." \
     http://127.0.0.1:8080/agents
2

Bring your own token

Set your own bearer token before starting:
export PRAISONAI_API_TOKEN=your-secret-token
praisonai deploy run --type api
Use your token in requests:
curl -H "Authorization: Bearer your-secret-token" \
     http://127.0.0.1:8080/agents
3

Disable auth (legacy)

Not recommended for production. Only use in trusted private networks.
Disable authentication explicitly:
export PRAISONAI_API_AUTH=disabled
export PRAISONAI_API_HOST=0.0.0.0  # Optional: bind to all interfaces
praisonai deploy run --type api

​
How It Works

ComponentPurpose
Bearer TokenSecret key required in Authorization header
Constant-time ComparisonPrevents timing oracle attacks
stderr OutputAuto-generated tokens printed securely
Environment OverridePRAISONAI_API_TOKEN for custom tokens

​
Environment Variables

VariableDefaultPurpose
PRAISONAI_API_AUTHenabledenabled (default) or disabled
PRAISONAI_API_TOKENauto-generatedBearer token required when auth is enabled. If unset, a 32-byte URL-safe random token is generated at startup and printed to stderr.
PRAISONAI_API_HOST127.0.0.1Bind host. Set to 0.0.0.0 only behind an authenticating proxy.
PRAISONAI_API_PORT8080Bind port.

​
Configuration Examples

# Default secure setup
praisonai deploy run --type api

# Custom token
export PRAISONAI_API_TOKEN=my-secret-key-123
praisonai deploy run --type api

# Disable auth (not recommended)
export PRAISONAI_API_AUTH=disabled
praisonai deploy run --type api

# Bind to all interfaces with auth
export PRAISONAI_API_HOST=0.0.0.0
export PRAISONAI_API_TOKEN=secure-token
praisonai deploy run --type api

​
APIConfig Reference

The APIConfig class in praisonai.deploy.models now defaults to secure settings: 
deploy:
  type: api
  api:
    host: 127.0.0.1        # Changed from 0.0.0.0
    port: 8080
    workers: 1
    cors_enabled: true
    auth_enabled: true     # Changed from false

​
Before vs After 4.6.34

 deploy:
   type: api
   api:
-    host: 0.0.0.0
+    host: 127.0.0.1
     port: 8080
     workers: 1
     cors_enabled: true
-    auth_enabled: false
+    auth_enabled: true

​
Security Details

​
Security Features

  • Constant-time token comparison using secrets.compare_digest() prevents timing oracle attacks
  • Auto-generated tokens are cryptographically secure (32 bytes, URL-safe)
  • stderr output only - tokens never appear in HTTP responses or logs
  • Localhost binding by default - reduces attack surface
  • Unauthenticated health endpoint at /health for monitoring

​
Token Generation

# Equivalent to the auto-generation process
import secrets
token = secrets.token_urlsafe(32)  # 43 character URL-safe string

​
Common Patterns

​
cURL Examples

# Get available agents
curl -H "Authorization: Bearer YOUR_TOKEN" \
     http://127.0.0.1:8080/agents

# Chat with agent
curl -X POST http://127.0.0.1:8080/chat \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"message": "Hello, how can you help me?"}'

# Health check (no auth required)
curl http://127.0.0.1:8080/health

​
Python Requests

import requests

# Set up session with auth
session = requests.Session()
session.headers.update({
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
})

# Get agents
response = session.get("http://127.0.0.1:8080/agents")
agents = response.json()

# Chat with agent
response = session.post("http://127.0.0.1:8080/chat", json={
    "message": "What is artificial intelligence?"
})
chat_response = response.json()

​
Environment File Setup

# .env file
PRAISONAI_API_TOKEN=your-secure-token-here
PRAISONAI_API_HOST=127.0.0.1
PRAISONAI_API_PORT=8080
PRAISONAI_API_AUTH=enabled

​
Migration from < 4.6.34

Quick fix for existing deployments:
# Disable auth and bind to all interfaces (like before)
export PRAISONAI_API_AUTH=disabled
export PRAISONAI_API_HOST=0.0.0.0
praisonai deploy run --type api
This removes security protections. Only use in trusted environments.
Recommended approach:
# Generate your own token
export PRAISONAI_API_TOKEN=$(openssl rand -base64 32)
praisonai deploy run --type api
echo "Your token: $PRAISONAI_API_TOKEN"
Store the token securely and update your clients.
Secure LAN deployment:
# Bind to all interfaces but keep auth enabled
export PRAISONAI_API_HOST=0.0.0.0
export PRAISONAI_API_TOKEN=your-secure-shared-token
praisonai deploy run --type api
Share the token only with trusted clients on your network.

​
Best Practices

  • Generate strong tokens: Use openssl rand -base64 32 or similar
  • Rotate tokens regularly: Update PRAISONAI_API_TOKEN and restart
  • Store securely: Never commit tokens to version control
  • Use environment variables: Keep tokens out of configuration files
  • Scope tokens appropriately: Different tokens for dev/staging/prod
  • Default localhost binding: Keep host: 127.0.0.1 unless necessary
  • TLS termination: Front with nginx/cloudflare for HTTPS
  • Firewall rules: Restrict port 8080 access to known sources
  • VPN access: Use VPN instead of public exposure when possible
  • Development: Use auto-generated tokens, localhost binding
  • Staging: Custom tokens, restricted network access
  • Production: Strong tokens, TLS frontend, monitoring
  • CI/CD: Separate tokens per environment, secret management
  • Monitor /health: Unauthenticated endpoint for status checks
  • Log 401 responses: Track authentication failures
  • Alert on token exposure: Watch for tokens in logs/errors
  • Audit token usage: Track which clients use which tokens

Security Best Practices

Overall security guidance for PraisonAI deployments

Agents API Reference

HTTP API endpoints for Agent.launch() servers (different authentication)