OrkaJS
Orka.JS

Permissions & Access Control

Enterprise-ready Role-Based Access Control (RBAC) for AI agents.Permissions, audit logging, and team management forsecure agent governance.

OrkaJS provides a comprehensive Role-Based Access Control (RBAC) system for managing who can access, execute, edit, and clone your AI agents. Combined with audit logging, you get full traceability for enterprise compliance.

Permission Actions

read, execute, edit, clone, delete, admin

Principal Types

user, team, role, service

Conditional Access

Time ranges, IP whitelist, rate limits

Audit Logging

Full traceability of all actions

Quick Start

import { 
  PermissionManager, 
  AuditLogger,
  globalPermissionManager,
  globalAuditLogger 
} from '@orka-js/agent';
 
// Create managers (or use global instances)
const permissions = new PermissionManager();
const audit = new AuditLogger();
 
// Set permissions for an agent
permissions.setPermissions('sales-agent', {
  agentId: 'sales-agent',
  owner: 'user:admin',
  rules: [
    { action: 'read', principals: ['team:sales', 'team:marketing'] },
    { action: 'execute', principals: ['role:sales-rep'] },
    { action: 'edit', principals: ['role:admin'] },
    { action: 'clone', principals: ['role:developer'] }
  ]
});
 
// Register user memberships
permissions.registerPrincipalMemberships('user:john', [
  'team:sales',
  'role:sales-rep'
]);
 
// Check permission
const result = permissions.check({
  principal: { type: 'user', id: 'john' },
  action: 'execute',
  agentId: 'sales-agent'
});
 
if (result.allowed) {
  // Execute agent and log
  audit.logAgentExecuted(
    { type: 'user', id: 'john' },
    'sales-agent',
    'success',
    { input: 'Qualify lead', output: 'Lead qualified' }
  );
} else {
  // Log access denied
  audit.logAccessDenied(
    { type: 'user', id: 'john' },
    'sales-agent',
    'execute',
    result.reason
  );
}

Permission Actions

ActionDescription
readView agent details and configuration
executeRun the agent with inputs
editModify agent configuration
cloneCreate a copy of the agent
deleteRemove the agent
adminFull control (owner only)

Principal Types

Principals are entities that can have permissions. OrkaJS supports four types:

// User - Individual user
{ type: 'user', id: 'john' }
// In rules: 'user:john'
 
// Team - Group of users
{ type: 'team', id: 'sales' }
// In rules: 'team:sales'
 
// Role - Permission role
{ type: 'role', id: 'admin' }
// In rules: 'role:admin'
 
// Service - External service/API
{ type: 'service', id: 'crm-integration' }
// In rules: 'service:crm-integration'
 
// Wildcard - Match all
// In rules: '*' or 'user:*'

Conditional Permissions

Add conditions to permission rules for fine-grained access control:

permissions.setPermissions('sensitive-agent', {
  agentId: 'sensitive-agent',
  owner: 'user:admin',
  rules: [{
    action: 'execute',
    principals: ['team:operations'],
    conditions: [
      // Only during business hours (9 AM - 6 PM)
      {
        type: 'time_range',
        config: {
          allowedHours: { start: 9, end: 18 },
          allowedDays: [1, 2, 3, 4, 5] // Mon-Fri
        }
      },
      // Only from office IPs
      {
        type: 'ip_whitelist',
        config: {
          ips: ['192.168.1.0/24', '10.0.0.1']
        }
      }
    ]
  }]
});
 
// Check with context
const result = permissions.check({
  principal: { type: 'user', id: 'john' },
  action: 'execute',
  agentId: 'sensitive-agent',
  context: {
    ipAddress: '192.168.1.50'
  }
});
 
// Result includes condition evaluation details
console.log(result.evaluatedConditions);

Audit Logging

Track all agent-related actions for compliance and debugging:

import { AuditLogger } from '@orka-js/agent';
 
const audit = new AuditLogger({
  maxEvents: 10000,      // Max events to keep in memory
  eventTtlMs: 30 * 24 * 60 * 60 * 1000 // 30 days TTL
});
 
// Log various events
audit.logAgentRegistered(principal, 'new-agent');
audit.logAgentExecuted(principal, 'agent-id', 'success', { input, output });
audit.logAgentCloned(principal, 'source-agent', 'cloned-agent');
audit.logPermissionGranted(principal, 'agent-id', 'execute', ['team:sales']);
audit.logAccessDenied(principal, 'agent-id', 'execute', 'No matching rule');
 
// Query events
const events = audit.query({
  types: ['agent.executed', 'access.denied'],
  agentId: 'sales-agent',
  from: new Date('2025-01-01'),
  limit: 100
});
 
// Get statistics
const stats = audit.getStats();
console.log(stats.totalEvents);
console.log(stats.accessDeniedCount);
console.log(stats.topPrincipals);
console.log(stats.topAgents);
 
// Subscribe to events in real-time
audit.on('access.denied', (event) => {
  console.warn(`Access denied: ${event.principal.id} tried ${event.action} on ${event.agentId}`);
});
 
// Export for compliance
const jsonExport = audit.export();
const csvExport = audit.exportCsv();

Audit Event Types

agent.registeredAgent was registered
agent.updatedAgent was updated
agent.deletedAgent was deleted
agent.executedAgent was executed
agent.clonedAgent was cloned
permission.grantedPermission was granted
permission.revokedPermission was revoked
access.allowedAccess was allowed
access.deniedAccess was denied

Full Integration Example

import { 
  AgentRegistry, 
  PermissionManager, 
  AuditLogger,
  ReActAgent 
} from '@orka-js/agent';
import { OpenAIAdapter } from '@orka-js/openai';
 
// Initialize
const registry = new AgentRegistry();
const permissions = new PermissionManager();
const audit = new AuditLogger();
const llm = new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY });
 
// Register agent
const agent = await registry.register({
  id: 'sales-assistant',
  name: 'Sales Assistant',
  role: 'Lead qualification',
  version: '1.0.0',
  description: 'Qualifies leads and schedules follow-ups',
  metadata: {
    tags: ['sales', 'crm'],
    capabilities: ['email', 'calendar'],
    author: 'user:admin'
  }
}, { goal: 'Qualify leads', tools: [] }, 'react');
 
// Set permissions
permissions.setPermissions('sales-assistant', {
  agentId: 'sales-assistant',
  owner: 'user:admin',
  rules: [
    { action: 'read', principals: ['team:sales', 'team:marketing'] },
    { action: 'execute', principals: ['role:sales-rep', 'role:manager'] },
    { action: 'edit', principals: ['role:admin'] },
    { action: 'clone', principals: ['role:developer'] }
  ]
});
 
// Log registration
audit.logAgentRegistered({ type: 'user', id: 'admin' }, 'sales-assistant');
 
// Execute with permission check
async function executeAgent(userId: string, input: string) {
  const principal = { type: 'user' as const, id: userId };
 
  // Check permission
  const check = permissions.check({
    principal,
    action: 'execute',
    agentId: 'sales-assistant'
  });
 
  if (!check.allowed) {
    audit.logAccessDenied(principal, 'sales-assistant', 'execute', check.reason);
    throw new Error(`Access denied: ${check.reason}`);
  }
 
  audit.logAccessAllowed(principal, 'sales-assistant', 'execute', check.reason);
 
  try {
    const reactAgent = new ReActAgent({
      llm,
      goal: 'Qualify the lead',
      tools: [],
      maxSteps: 5
    });
 
    const result = await reactAgent.run(input);
 
    audit.logAgentExecuted(principal, 'sales-assistant', 'success', {
      input,
      output: result.output,
      steps: result.steps.length
    });
 
    return result;
  } catch (error) {
    audit.logAgentExecuted(principal, 'sales-assistant', 'failure', {
      input,
      error: (error as Error).message
    });
    throw error;
  }
}
 
// Usage
permissions.registerPrincipalMemberships('user:john', ['team:sales', 'role:sales-rep']);
await executeAgent('john', 'Qualify lead: Acme Corp, $50k budget');

Best Practices

Use Teams and Roles

Assign permissions to teams/roles instead of individual users for easier management.

Principle of Least Privilege

Grant only the minimum permissions needed. Start restrictive and add as needed.

Always Log Access Denied

Track denied access attempts to detect potential security issues or misconfigured permissions.

Use Conditions for Sensitive Agents

Add time-based or IP-based conditions for agents that handle sensitive data.

Regular Audit Reviews

Periodically review audit logs and statistics to identify unusual patterns.

🚀 What's Next?

Explore the Agent Platform to see how permissions integrate with the registry:

← Agent Platform