Skip to main content
Platform Authentication enables secure access to the PraisonAI Platform using JWT tokens for API authentication. Platform Authentication enables secure access to the PraisonAI Platform using JWT tokens for API authentication.
from praisonaiagents import Agent

agent = Agent(name="secure-assistant", instructions="Use JWT-authenticated platform APIs.")
agent.start("Call the platform with my bearer token.")
The user registers, logs in, and sends JWT bearer tokens on each API request for authorised access.

Quick Start

1

Start Platform Server

Install and start the PraisonAI Platform server to enable authentication endpoints:
from praisonai_platform.client import PlatformClient
import asyncio

async def setup_auth():
    # Initialize platform client
    client = PlatformClient("http://localhost:8000")
    
    # Register new user (auto-stores token)
    result = await client.register(
        email="user@example.com",
        password="securepassword", 
        name="John Doe"
    )
    
    print(f"User registered with ID: {result['user']['id']}")
    return client

# Run the authentication setup
client = asyncio.run(setup_auth())
2

Authenticate and Use Token

Once registered, use the JWT token for authenticated API requests:
import httpx
import asyncio

async def authenticated_request():
    # Login to get token
    async with httpx.AsyncClient(base_url="http://localhost:8000") as client:
        # Authenticate user
        auth_response = await client.post("/api/v1/auth/login", json={
            "email": "user@example.com",
            "password": "securepassword"
        })
        
        token = auth_response.json()["token"]
        
        # Use token for authenticated requests
        headers = {"Authorization": f"Bearer {token}"}
        user_info = await client.get("/api/v1/auth/me", headers=headers)
        
        print(f"Authenticated as: {user_info.json()['name']}")

asyncio.run(authenticated_request())

How It Works

ComponentPurposeSecurity
JWT TokenStateless authenticationSigned with secret key
Bearer HeaderToken transmissionStandard HTTP authorization
Password HashSecure storageBcrypt hashing
TTL ExpiryToken lifespanConfigurable timeout

API Reference

Authentication Endpoints

MethodEndpointPurposeAuthentication
POST/api/v1/auth/registerRegister new userNone
POST/api/v1/auth/loginLogin existing userNone
GET/api/v1/auth/meGet current userBearer Token

Request/Response Schemas

{
  "email": "user@example.com",
  "password": "securepassword",
  "name": "John Doe"
}

Configuration Options

Configure JWT authentication using environment variables:
VariableDefaultDescription
PLATFORM_JWT_SECRETdev-secret-change-meJWT signing secret (MUST change in production)
PLATFORM_JWT_TTL2592000 (30 days)Token time-to-live in seconds
PLATFORM_ENVdevSet to non-dev to enforce strong JWT secret
Security Notice: Always change PLATFORM_JWT_SECRET in production environments. Using the default secret poses a security risk.

Client Examples

# Start the platform server
pip install praisonai-platform
uvicorn praisonai_platform.api.app:create_app --factory --port 8000

# Register new user
curl -s -X POST http://localhost:8000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"mypassword","name":"John Doe"}' \
  --max-time 10

# Login with credentials  
curl -s -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"mypassword"}' \
  --max-time 10

# Get current user info (replace YOUR_TOKEN_HERE with actual token)
curl -s http://localhost:8000/api/v1/auth/me \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  --max-time 10

Common Patterns

Store JWT tokens securely for reuse across requests:
import os
import asyncio
from praisonai_platform.client import PlatformClient

async def persistent_auth():
    client = PlatformClient("http://localhost:8000")
    
    # Check for existing token in environment
    stored_token = os.getenv('PLATFORM_AUTH_TOKEN')
    
    if not stored_token:
        # Register or login to get new token
        result = await client.login("user@example.com", "password")
        stored_token = result['token']
        
        # Store token for future use
        os.environ['PLATFORM_AUTH_TOKEN'] = stored_token
    
    # Use stored token for requests
    client.set_token(stored_token)
    user_info = await client.get_current_user()
    print(f"Authenticated as: {user_info['name']}")

asyncio.run(persistent_auth())
Handle common authentication errors gracefully:
import httpx
import asyncio

async def robust_auth():
    async with httpx.AsyncClient(base_url="http://localhost:8000") as client:
        try:
            # Attempt login
            resp = await client.post("/api/v1/auth/login", json={
                "email": "user@example.com",
                "password": "mypassword"
            })
            resp.raise_for_status()
            
            token = resp.json()["token"]
            print(f"Authentication successful")
            
        except httpx.HTTPStatusError as e:
            if e.response.status_code == 401:
                print("Invalid credentials - check email/password")
            elif e.response.status_code == 404:
                print("User not found - register first")
            else:
                print(f"Authentication failed: {e}")
        except Exception as e:
            print(f"Network error: {e}")

asyncio.run(robust_auth())
Manage authentication for multiple users in the same application:
import asyncio
from typing import Dict
from praisonai_platform.client import PlatformClient

class MultiUserAuth:
    def __init__(self, base_url: str):
        self.base_url = base_url
        self.user_tokens: Dict[str, str] = {}
    
    async def authenticate_user(self, email: str, password: str):
        client = PlatformClient(self.base_url)
        
        # Check if user is already authenticated
        if email in self.user_tokens:
            return self.user_tokens[email]
        
        # Login and store token
        result = await client.login(email, password)
        self.user_tokens[email] = result['token']
        
        return result['token']
    
    async def get_user_client(self, email: str) -> PlatformClient:
        if email not in self.user_tokens:
            raise ValueError(f"User {email} not authenticated")
        
        client = PlatformClient(self.base_url)
        client.set_token(self.user_tokens[email])
        return client

async def multi_user_example():
    auth_manager = MultiUserAuth("http://localhost:8000")
    
    # Authenticate multiple users
    await auth_manager.authenticate_user("admin@example.com", "admin_pass")
    await auth_manager.authenticate_user("user@example.com", "user_pass")
    
    # Use clients for different users
    admin_client = await auth_manager.get_user_client("admin@example.com")
    user_client = await auth_manager.get_user_client("user@example.com")
    
    admin_info = await admin_client.get_current_user()
    user_info = await user_client.get_current_user()
    
    print(f"Admin: {admin_info['name']}")
    print(f"User: {user_info['name']}")

asyncio.run(multi_user_example())

Testing

Verify authentication functionality with comprehensive tests:
# Install test dependencies
pip install praisonai-platform[test]
This single command installs every dependency required for pytest collection and execution, including email-validator for EmailStr schemas — no manual follow-up installs.
# Run authentication service tests
pytest tests/test_services.py::TestAuthService -v

# Run API integration tests  
pytest tests/test_api_integration.py::TestAuthErrors -v

# Run all authentication tests
pytest tests/ -k "auth" -v
Tests require a running platform server instance. Start the server before running tests:
uvicorn praisonai_platform.api.app:create_app --factory --port 8000

Best Practices

  • Never log tokens: Avoid printing or logging JWT tokens in production
  • Environment variables: Store tokens in environment variables, not source code
  • Token rotation: Implement token refresh for long-running applications
  • Secure transport: Always use HTTPS in production to protect token transmission
  • Strong passwords: Enforce minimum password complexity requirements
  • Password hashing: Platform uses bcrypt for secure password storage
  • Rate limiting: Implement rate limiting on authentication endpoints
  • Account lockout: Consider implementing account lockout after failed attempts
  • Change JWT secret: Always set a strong, unique PLATFORM_JWT_SECRET in production
  • Token expiry: Set appropriate PLATFORM_JWT_TTL based on security requirements
  • Environment validation: Set PLATFORM_ENV to non-dev to enable production security checks
  • HTTPS only: Never expose authentication endpoints over HTTP in production
  • Graceful degradation: Handle authentication failures gracefully
  • Clear error messages: Provide helpful error messages for common auth issues
  • Retry logic: Implement exponential backoff for transient failures
  • Fallback mechanisms: Consider offline capabilities when authentication is unavailable

Platform API

Complete platform API documentation

Security Features

Advanced security and protection features