> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Platform Authentication
> JWT-based authentication for PraisonAI Platform with register, login, and Bearer token support
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.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
subgraph "Authentication Flow"
Register[📝 Register] --> Login[🔑 Login]
Login --> Token[🎫 JWT Token]
Token --> API[🔌 API Calls]
end
classDef register fill:#6366F1,stroke:#7C90A0,color:#fff
classDef auth fill:#F59E0B,stroke:#7C90A0,color:#fff
classDef api fill:#10B981,stroke:#7C90A0,color:#fff
class Register register
class Login,Token auth
class API api
classDef agent fill:#8B0000,color:#fff
classDef tool fill:#189AB4,color:#fff
```
## Quick Start
Install and start the PraisonAI Platform server to enable authentication endpoints:
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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())
```
Once registered, use the JWT token for authenticated API requests:
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
participant Client
participant Platform API
participant Auth Service
participant Database
Client->>Platform API: POST /api/v1/auth/register
Platform API->>Auth Service: Create User
Auth Service->>Database: Store User Data
Database-->>Auth Service: User Created
Auth Service-->>Platform API: JWT Token
Platform API-->>Client: {token, user}
Client->>Platform API: POST /api/v1/auth/login
Platform API->>Auth Service: Validate Credentials
Auth Service->>Database: Check User
Database-->>Auth Service: User Valid
Auth Service-->>Platform API: JWT Token
Platform API-->>Client: {token, user}
Client->>Platform API: GET /api/v1/auth/me (Bearer token)
Platform API->>Auth Service: Verify JWT
Auth Service-->>Platform API: User Info
Platform API-->>Client: User Details
```
| Component | Purpose | Security |
| ----------------- | ------------------------ | --------------------------- |
| **JWT Token** | Stateless authentication | Signed with secret key |
| **Bearer Header** | Token transmission | Standard HTTP authorization |
| **Password Hash** | Secure storage | Bcrypt hashing |
| **TTL Expiry** | Token lifespan | Configurable timeout |
***
## API Reference
### Authentication Endpoints
| Method | Endpoint | Purpose | Authentication |
| ------ | ----------------------- | ------------------- | -------------- |
| `POST` | `/api/v1/auth/register` | Register new user | None |
| `POST` | `/api/v1/auth/login` | Login existing user | None |
| `GET` | `/api/v1/auth/me` | Get current user | Bearer Token |
### Request/Response Schemas
```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
"email": "user@example.com",
"password": "securepassword",
"name": "John Doe"
}
```
```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
"email": "user@example.com",
"password": "securepassword"
}
```
```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
"token": "eyJhbGciOiJIUzI1NiIs...",
"user": {
"id": "abc123",
"name": "John Doe",
"email": "user@example.com",
"created_at": "2025-01-01T00:00:00"
}
}
```
```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
"id": "abc123",
"name": "John Doe",
"email": "user@example.com",
"created_at": "2025-01-01T00:00:00"
}
```
***
## Configuration Options
Configure JWT authentication using environment variables:
| Variable | Default | Description |
| --------------------- | ---------------------- | -------------------------------------------------- |
| `PLATFORM_JWT_SECRET` | `dev-secret-change-me` | JWT signing secret (**MUST change in production**) |
| `PLATFORM_JWT_TTL` | `2592000` (30 days) | Token time-to-live in seconds |
| `PLATFORM_ENV` | `dev` | Set 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
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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
```
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import asyncio
from praisonai_platform.client import PlatformClient
async def authentication_example():
client = PlatformClient("http://localhost:8000")
# Register new user (auto-stores token)
register_result = await client.register(
"user@example.com",
"mypassword",
"John Doe"
)
print(f"Registered user ID: {register_result['user']['id']}")
# Login existing user (if already registered)
login_result = await client.login(
"user@example.com",
"mypassword"
)
print(f"Login token: {login_result['token'][:20]}...")
asyncio.run(authentication_example())
```
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import httpx
import asyncio
async def direct_auth_example():
async with httpx.AsyncClient(base_url="http://localhost:8000") as client:
# Register new user
register_resp = await client.post("/api/v1/auth/register", json={
"email": "user@example.com",
"password": "mypassword",
"name": "John Doe"
})
token = register_resp.json()["token"]
# Use token for authenticated requests
headers = {"Authorization": f"Bearer {token}"}
me_resp = await client.get("/api/v1/auth/me", headers=headers)
user_info = me_resp.json()
print(f"Authenticated as: {user_info['name']}")
print(f"Email: {user_info['email']}")
asyncio.run(direct_auth_example())
```
***
## Common Patterns
Store JWT tokens securely for reuse across requests:
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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:
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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:
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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:
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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.
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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:
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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
***
## Related
Complete platform API documentation
Advanced security and protection features