Authentication

PLai Framework uses multiple authentication methods depending on the context. This guide covers all authentication scenarios you’ll encounter.

Dashboard Authentication

Create Account

Visit the PLai Framework dashboard and click “Register”

Email Verification

Check your email and click the verification link

Organization Setup

Create your first organization or accept an invitation

Project Access

Create a project or get invited to existing projects

Session Management

PLai Framework uses secure session cookies for dashboard authentication:

Session Duration: Sessions last 30 days by default
Auto-Renewal: Sessions renew automatically with activity
Secure Cookies: All cookies are httpOnly and secure

API Authentication

JWT Tokens

API access uses JWT (JSON Web Tokens) for authentication:

// Example API call with JWT
const response = await fetch('https://api.plaisolutions.com/agents', {
  headers: {
    'Authorization': `Bearer ${jwt_token}`,
    'Content-Type': 'application/json'
  }
});

Token Types

User JWT

Authenticates user actions and personal resources

Project JWT

Provides access to project-specific resources

Obtaining Tokens

Dashboard Method:

// Tokens are automatically stored in cookies
const user_jwt = getCookie('user_jwt');
const project_jwt = getCookie('project_jwt');

API Method:

curl -X POST https://api.plaisolutions.com/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "password"}'

Organization & Project Access

Role-Based Access Control (RBAC)

PLai Framework implements fine-grained RBAC:

Organization Roles

Owner: Full organization control
Admin: Manage users and projects
Member: Access assigned projects
Viewer: No access

Project Roles

Owner: Full project control
Admin: Manage project resources
Member: Use agents, datasources and tools as project member
Viewer: Read-only access

Permission Matrix

Action	Viewer	Member	Admin	Owner
View Agents	✅	✅	✅	✅
Chat with Agents	✅	✅	✅	✅
Create Agents	❌	✅	✅	✅
Manage Tools & Datasources	❌	✅	✅	✅
View Analytics	❌	✅	✅	✅
Manage Batches	❌	✅	✅	✅
Billing Access	❌	❌	❌	✅

API Security

Rate Limiting

We’re working on it.

Request Headers

Always include these headers in API requests:

const headers = {
  'Authorization': `Bearer ${jwt_token}`,
  'Content-Type': 'application/json',
  'User-Agent': 'YourApp/1.0.0',
  'X-API-Version': '1.0'
};

Environment-Specific Configuration

Development Environment

const config = {
  apiUrl: 'https://staging.api.plaisolutions.com',
  dashboardUrl: 'https://staging.framework.plaisolutions.com'
};

Production Environment

const config = {
  apiUrl: 'https://api.plaisolutions.com',
  dashboardUrl: 'https://framework.plaisolutions.com'
};

Error Handling

Common Authentication Errors

{
  "error": "unauthorized",
  "message": "Invalid or expired token",
  "code": 401
}

{
  "error": "forbidden",
  "message": "Insufficient permissions",
  "code": 403
}

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests",
  "code": 429,
  "retry_after": 60
}

Error Response Handling

async function handleApiRequest(url: string, options: RequestInit) {
  const response = await fetch(url, options);
  
  if (response.status === 401) {
    // Token expired, redirect to login
    window.location.href = '/auth/login';
    return;
  }
  
  if (response.status === 403) {
    // Insufficient permissions
    throw new Error('You do not have permission to perform this action');
  }
  
  if (response.status === 429) {
    // Rate limited
    const retryAfter = response.headers.get('Retry-After');
    throw new Error(`Rate limited. Retry after ${retryAfter} seconds`);
  }
  
  return response.json();
}

Security Best Practices

Never expose JWT tokens in client-side code or logs. Always use secure storage methods.

Rotate tokens regularly and implement proper token refresh mechanisms for long-running applications.

Token Storage

Web Applications
Mobile Applications
Server Applications

Use httpOnly cookies for automatic inclusion
Store in secure sessionStorage for manual handling
Never use localStorage for sensitive tokens

Next Steps

Quick Start

Set up your first authenticated project

API Reference

Explore API endpoints and examples

​Authentication

​Dashboard Authentication

​User Registration & Login

​Session Management

​API Authentication

​JWT Tokens

​Token Types

User JWT

Project JWT

​Obtaining Tokens

​Organization & Project Access

​Role-Based Access Control (RBAC)

​Permission Matrix

​API Security

​Rate Limiting

​Request Headers

​Environment-Specific Configuration

​Development Environment

​Production Environment

​Error Handling

​Common Authentication Errors

​Error Response Handling

​Security Best Practices

​Token Storage

​Next Steps

Quick Start

API Reference

Authentication

Dashboard Authentication

User Registration & Login

Session Management

API Authentication

JWT Tokens

Token Types

Obtaining Tokens

Organization & Project Access

Role-Based Access Control (RBAC)

Permission Matrix

API Security

Rate Limiting

Request Headers

Environment-Specific Configuration

Development Environment

Production Environment

Error Handling

Common Authentication Errors

Error Response Handling

Security Best Practices

Token Storage

Next Steps