Skip to content

Authentication API

Complete authentication, authorization, and session management API reference.

Overview

Champa Intelligence uses JWT (JSON Web Token) based authentication with role-based access control (RBAC). All API endpoints require authentication except /auth/login.

Authentication Flow

sequenceDiagram
    participant Client
    participant API
    participant Redis
    participant Database

    Client->>API: POST /auth/login
    API->>Database: Verify credentials
    Database-->>API: User data
    API->>API: Generate JWT
    API->>Redis: Store session
    API-->>Client: JWT token + cookie

    Client->>API: GET /api/resource (with JWT)
    API->>Redis: Validate session
    Redis-->>API: Session valid
    API->>API: Check permissions
    API-->>Client: Resource data
Hold "Alt" / "Option" to enable pan & zoom

Endpoints

Login

Authenticate a user and receive a JWT token.

POST /auth/login

Request Body:

{
  "username": "admin",
  "password": "admin123",
  "remember_me": false
}

Parameters:

Field Type Required Description
username string Yes Username
password string Yes User password
remember_me boolean No Extend session to 30 days (default: false)

Response: 200 OK

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoxLCJ1c2VybmFtZSI6ImFkbWluIiwicm9sZSI6ImFkbWluaXN0cmF0b3IiLCJleHAiOjE3NDI0NjgwMDB9.signature",
  "user": {
    "id": 1,
    "username": "admin",
    "email": "admin@company.com",
    "role": "administrator",
    "permissions": [
      "full_access",
      "manage_users",
      "manage_roles"
    ]
  },
  "expires_at": "2025-01-16T10:30:00"
}

Error Response: 401 Unauthorized

{
  "success": false,
  "error": "Invalid credentials"
}

Account Locked Response: 403 Forbidden

{
  "success": false,
  "error": "Account locked due to multiple failed login attempts",
  "locked_until": "2025-01-15T11:00:00"
}

Example:

curl -X POST http://localhost:8088/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "admin123",
    "remember_me": false
  }'

import requests

response = requests.post(
    'http://localhost:8088/auth/login',
    json={
        'username': 'admin',
        'password': 'admin123',
        'remember_me': False
    }
)

if response.status_code == 200:
    data = response.json()
    token = data['token']
    print(f"Logged in as {data['user']['username']}")
else:
    print(f"Login failed: {response.json()['error']}")

const response = await fetch('http://localhost:8088/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    username: 'admin',
    password: 'admin123',
    remember_me: false
  })
});

if (response.ok) {
  const data = await response.json();
  console.log(`Logged in as ${data.user.username}`);
  localStorage.setItem('token', data.token);
} else {
  const error = await response.json();
  console.error(`Login failed: ${error.error}`);
}

Permissions

Available Permissions

Permission Description
full_access Complete system access (administrators only)
api_access Programmatic API access
portfolio_data Portfolio dashboard access
extended_dashboard_data Process intelligence dashboard
bpmn_analysis_data BPMN analytics viewer
dmn_analysis_data DMN analytics
health_monitor_data Health monitoring
journey_analysis_data Journey monitoring
ai_analysis_data AI-powered analysis
diff_tool_data BPMN diff tool
model_validation_data Model validator/linter
manage_users User management
manage_roles Role management

Security Features

Brute Force Protection

The system automatically locks accounts after 5 failed login attempts within 15 minutes.

Lock Duration: 30 minutes

Response when locked:

{
  "success": false,
  "error": "Account locked due to multiple failed login attempts",
  "locked_until": "2025-01-15T11:00:00",
  "retry_after": 1800
}

Password Requirements

  • Minimum 8 characters
  • At least one uppercase letter
  • At least one lowercase letter
  • At least one number
  • Optional: Special characters

Token Expiration

Token Type Default TTL Max TTL
User Session 24 hours 30 days (with remember_me)
API Token 90 days 365 days or never

Error Handling

Common Error Responses

Invalid Credentials:

{
  "success": false,
  "error": "Invalid credentials",
  "status_code": 401
}

Insufficient Permissions:

{
  "success": false,
  "error": "Insufficient permissions to access this resource",
  "required_permission": "manage_users",
  "status_code": 403
}

Token Expired:

{
  "success": false,
  "error": "Token has expired",
  "expired_at": "2025-01-15T10:00:00",
  "status_code": 401
}

Account Disabled:

{
  "success": false,
  "error": "Account is disabled",
  "status_code": 403
}

Best Practices

1. Secure Token Storage

Browser: 

// Use secure, httpOnly cookies
// Or store in memory only (not localStorage)
const token = response.data.token;
sessionStorage.setItem('token', token); // Better than localStorage

Server-side: 

# Use environment variables
import os
API_TOKEN = os.getenv('CHAMPA_API_TOKEN')

2. Token Refresh Strategy

def make_authenticated_request(url, token):
    response = requests.get(url, headers={'Authorization': f'Bearer {token}'})

    if response.status_code == 401:
        # Token expired, re-authenticate
        new_token = login(username, password)
        return make_authenticated_request(url, new_token)

    return response

3. Use API Users for Automation

Don't use personal accounts for scripts and automation. Create dedicated API users:

# Good: Dedicated API user
api_client = ChampaClient('http://localhost:8088', API_TOKEN)

# Bad: Personal account credentials in code
api_client = ChampaClient('http://localhost:8088', login('admin', 'password'))

Next Steps

Support

For authentication issues: