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.

Platform authentication requires proper JWT secret configuration for security in production environments.

​
Quick Start

1

Set JWT Secret for Production

# Generate a secure secret
python -c "import secrets; print(secrets.token_urlsafe(64))"
# Example output: kV8fTqZ2Jm5nR9sQ3xW8vY1bN7pL4dF6hG0jK9sA2cE5mZ8xW...

# Set the environment variable
export PLATFORM_JWT_SECRET="your-generated-secret-here"
2

Start Platform Service

# With custom secret (production)
export PLATFORM_JWT_SECRET="kV8fTqZ2Jm5nR9sQ3xW8vY1bN7pL4dF6..."
praisonai-platform start

# Or for development (allows default secret)
export PLATFORM_ENV=dev
praisonai-platform start

​
Configuration

​
Required Environment Variables

VariablePurposeRequired
PLATFORM_JWT_SECRETSecret for JWT token signingYes (except dev)
PLATFORM_ENVEnvironment mode (dev or production)Optional (defaults to production)
PLATFORM_JWT_TTLToken TTL in secondsOptional (default: 30 days)

​
JWT Secret Security

Breaking Change: The platform now refuses to issue JWTs when running with the default secret outside PLATFORM_ENV=dev.
# ✅ Valid configurations
export PLATFORM_JWT_SECRET="your-secure-secret"  # Production with custom secret
export PLATFORM_ENV=dev                          # Development (default secret OK)

# ❌ Invalid configuration (will fail)
# No PLATFORM_JWT_SECRET set and PLATFORM_ENV != "dev"

​
How It Works

The AuthService._issue_token method enforces JWT secret validation: 
def _issue_token(self, user: User) -> str:
    """Issue a JWT for a user."""
    if JWT_SECRET == _DEFAULT_SECRET and os.environ.get("PLATFORM_ENV", "dev") != "dev":
        raise RuntimeError(
            "Refusing to issue JWT with default PLATFORM_JWT_SECRET outside dev"
        )
    # ... issue JWT

​
Token Issuance Flow

​
Production Deployment

​
Docker Configuration

FROM python:3.11-slim

# Set JWT secret via environment
ENV PLATFORM_JWT_SECRET="your-secure-secret-from-secrets-manager"

# Install and run platform
RUN pip install praisonai-platform
CMD ["praisonai-platform", "start"]

​
Kubernetes Secret

apiVersion: v1
kind: Secret
metadata:
  name: platform-auth
type: Opaque
data:
  jwt-secret: eW91ci1zZWN1cmUtc2VjcmV0LWJhc2U2NC1lbmNvZGVk
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: praisonai-platform
spec:
  template:
    spec:
      containers:
      - name: platform
        image: praisonai/platform:latest
        env:
        - name: PLATFORM_JWT_SECRET
          valueFrom:
            secretKeyRef:
              name: platform-auth
              key: jwt-secret

​
Environment Variable Best Practices

# Use a secrets manager
export PLATFORM_JWT_SECRET="$(aws secretsmanager get-secret-value --secret-id prod/jwt-secret --query SecretString --output text)"

# Or read from file
export PLATFORM_JWT_SECRET="$(cat /var/secrets/jwt-secret)"

# Verify it's set
echo ${PLATFORM_JWT_SECRET:0:10}...  # Show first 10 characters only

​
Migration

​
Upgrading from Previous Versions

If you’re upgrading from a version without JWT secret validation, set PLATFORM_JWT_SECRET before restarting, or you’ll get a RuntimeError when users try to log in.
1

Generate Secret

# Generate a cryptographically secure secret
python -c "import secrets; print('PLATFORM_JWT_SECRET=' + secrets.token_urlsafe(64))"
2

Update Configuration

# Add to your environment/config
export PLATFORM_JWT_SECRET="your-generated-secret"

# Or for temporary local development
export PLATFORM_ENV=dev  # NOT for production
3

Restart Platform

# Restart with new configuration
praisonai-platform restart

​
Error Handling

When login() is called with misconfigured production deployment: 
RuntimeError: Refusing to issue JWT with default PLATFORM_JWT_SECRET outside dev
This error occurs during token issuance, not service startup, so the platform will start successfully but fail when users attempt to authenticate.

​
Development vs Production

​
Development Mode

# Allow default secret (insecure, development only)
export PLATFORM_ENV=dev
praisonai-platform start

# Default secret warning will be logged but service continues

​
Production Mode

# Require custom secret (secure, production)
export PLATFORM_JWT_SECRET="$(python -c 'import secrets; print(secrets.token_urlsafe(64))')"
unset PLATFORM_ENV  # Defaults to production mode
praisonai-platform start
ModeDefault SecretCustom SecretNotes
Development (PLATFORM_ENV=dev)✅ Allowed✅ AllowedFor local development only
Production (any other PLATFORM_ENV)❌ Rejected✅ RequiredEnforced at token issuance

​
Best Practices

Generate secrets with at least 256 bits of entropy using secrets.token_urlsafe(64) or equivalent. Never use predictable values.
Implement secret rotation every 90 days. When rotating, issue new tokens gradually to avoid service disruption.
Use dedicated secret management systems (AWS Secrets Manager, HashiCorp Vault, etc.) rather than plain environment variables.
Log and alert on RuntimeError exceptions during login to detect misconfigured deployments quickly.

RBAC Enforcement

Workspace membership and role-based access control

Platform SDK

Python SDK for platform integration