Authentication
PLai Framework uses multiple authentication methods depending on the context. This guide covers all authentication scenarios you’ll encounter.
Dashboard Authentication
User Registration & Login
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
- Multi-Device: You can be logged in on multiple devices
- 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');
curl -X POST https://api.plaisolutions.com/auth/login \
-H "Content-Type: application/json" \
-d '{"email": "[email protected]", "password": "password"}'
Agent Chat Authentication
Share URLs
Agents can be shared publicly or with specific users using secure share URLs:
https://framework.plaisolutions.com/share/{agentId}/{shareId}
Public Shares
Private Shares
- No authentication required
- Time-limited access
- Rate limiting applied
- Limited functionality
- Authentication required
- Full agent capabilities
- Usage tracked to organization
- Full analytics available
Organization & Project Access
Role-Based Access Control (RBAC)
PLai Framework implements fine-grained RBAC:
- Owner: Full organization control
- Admin: Manage users and projects
- Member: Access assigned projects
- Owner: Full project control
- Admin: Manage project resources
- Member: Use agents and tools
- Viewer: Read-only access
Permission Matrix
| Action | Viewer | Member | Admin | Owner |
|---|
| View Agents | ✅ | ✅ | ✅ | ✅ |
| Chat with Agents | ❌ | ✅ | ✅ | ✅ |
| Create Agents | ❌ | ❌ | ✅ | ✅ |
| Manage Tools | ❌ | ❌ | ✅ | ✅ |
| View Analytics | ✅ | ✅ | ✅ | ✅ |
| Manage Batches | ❌ | ❌ | ✅ | ✅ |
| Billing Access | ❌ | ❌ | ❌ | ✅ |
API Security
Rate Limiting
API endpoints have rate limits to prevent abuse:
- Authentication: 10 requests/minute
- Agent Chat: 60 requests/minute
- Management APIs: 300 requests/minute
- Analytics: 100 requests/minute
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://api-dev.plaisolutions.com',
authUrl: 'https://auth-dev.plaisolutions.com',
dashboardUrl: 'https://app-dev.plaisolutions.com'
};
Production Environment
const config = {
apiUrl: 'https://api.plaisolutions.com',
authUrl: 'https://auth.plaisolutions.com',
dashboardUrl: 'https://framework.plaisolutions.com'
};
Error Handling
Common Authentication Errors
{
"error": "unauthorized",
"message": "Invalid or expired token",
"code": 401
}
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
- Use secure keychain/keystore storage
- Implement biometric authentication where available
- Clear tokens on app logout or uninstall
- Use environment variables or secure vaults
- Implement token refresh logic
- Log authentication events for audit
Integration Examples
React Application
import { useAuth } from '@/hooks/useAuth';
function MyComponent() {
const { user, project, isAuthenticated, login, logout } = useAuth();
if (!isAuthenticated) {
return <LoginForm onLogin={login} />;
}
return (
<div>
<h1>Welcome, {user.name}</h1>
<p>Current project: {project.name}</p>
<button onClick={logout}>Logout</button>
</div>
);
}
Node.js Application
import jwt from 'jsonwebtoken';
async function authenticateRequest(req: Request, res: Response, next: NextFunction) {
const token = req.headers.authorization?.replace('Bearer ', '');
if (!token) {
return res.status(401).json({ error: 'No token provided' });
}
try {
const decoded = jwt.verify(token, process.env.JWT_SECRET);
req.user = decoded;
next();
} catch (error) {
return res.status(401).json({ error: 'Invalid token' });
}
}
Next Steps
