Skip to main content

​
Role Examples

This page provides complete examples of setting up role-based access control.

​
Example 1: Department-Based Access

Your company has HR, Finance, and IT departments. Each should only see their own documents.

​
Step 1: Define Roles

hr          - HR team members
finance     - Finance team members
it          - IT team members
all-staff   - Everyone (for company-wide docs)

​
Step 2: Upload Documents with Roles

# HR documents
curl -X POST .../documents/upload \
  -H "X-External-Roles: [\"admin\"]" \
  -F "[email protected]" \
  -F "aclRoles=hr"

# Finance documents
curl -X POST .../documents/upload \
  -H "X-External-Roles: [\"admin\"]" \
  -F "[email protected]" \
  -F "aclRoles=finance"

# Company-wide documents
curl -X POST .../documents/upload \
  -H "X-External-Roles: [\"admin\"]" \
  -F "[email protected]" \
  -F "aclRoles=all-staff"

​
Step 3: Query with Roles

HR Manager queries: 
X-External-Roles: ["hr", "all-staff"]
→ Sees: HR docs + company-wide docs Finance Analyst queries: 
X-External-Roles: ["finance", "all-staff"]
→ Sees: Finance docs + company-wide docs CEO queries: 
X-External-Roles: ["hr", "finance", "it", "all-staff", "executive"]
→ Sees: All documents

​
Example 2: Hierarchy-Based Access

Control access based on organizational hierarchy.

​
Roles

employee    - All employees
manager     - Middle management
director    - Department directors
executive   - C-suite executives

​
Document ACLs

Document TypeACL
General Infoemployee
Team Guidelinesmanager
Strategic Plansdirector
Board Reportsexecutive

​
Request Examples

Regular Employee: 
X-External-Roles: ["employee"]
→ Sees: General Info only Manager: 
X-External-Roles: ["employee", "manager"]
→ Sees: General Info + Team Guidelines Director: 
X-External-Roles: ["employee", "manager", "director"]
→ Sees: General Info + Team Guidelines + Strategic Plans

​
Example 3: Project-Based Access

Multiple projects with separate teams.

​
Roles

project-alpha   - Project Alpha team
project-beta    - Project Beta team
project-gamma   - Project Gamma team
project-lead    - All project leads
engineering     - All engineers

​
Document Structure

/project-alpha/
  └── specs.pdf (aclRoles: project-alpha, project-lead)
  └── design.pdf (aclRoles: project-alpha)
  
/project-beta/
  └── specs.pdf (aclRoles: project-beta, project-lead)
  
/engineering/
  └── standards.pdf (aclRoles: engineering)

​
Request Examples

Alpha Team Member: 
X-External-Roles: ["project-alpha", "engineering"]
→ Sees: Alpha docs + Engineering standards → Does NOT see: Beta or Gamma docs Project Lead (oversees all): 
X-External-Roles: ["project-lead", "engineering"]
→ Sees: Specs from all projects + Engineering standards → Does NOT see: Detailed design docs (needs specific project role)

​
Example 4: Access Levels

Simple tiered access model.

​
Roles

public      - Basic access
internal    - Internal employees
confidential - Sensitive access
restricted  - Highly sensitive

​
Implementation

function getRolesForAccessLevel(level) {
  const levels = ['public', 'internal', 'confidential', 'restricted'];
  const index = levels.indexOf(level);
  return levels.slice(0, index + 1);
}

// User with "internal" clearance
getRolesForAccessLevel('internal')
// Returns: ['public', 'internal']

// User with "confidential" clearance
getRolesForAccessLevel('confidential')
// Returns: ['public', 'internal', 'confidential']

​
Usage

async function queryWithClearance(userId, clearanceLevel, question) {
  const roles = getRolesForAccessLevel(clearanceLevel);
  
  return await api.chat({
    message: question,
    headers: {
      'X-External-User-Id': userId,
      'X-External-Roles': JSON.stringify(roles)
    }
  });
}

​
Visual Summary

┌─────────────────────────────────────────────┐
│ User: Alice                                 │
│ Roles: [hr, manager, all-staff]             │
├─────────────────────────────────────────────┤
│                                             │
│  Documents Alice CAN access:                │
│  ✅ Employee Handbook (all-staff)           │
│  ✅ HR Policies (hr)                        │
│  ✅ Management Guide (manager)              │
│                                             │
│  Documents Alice CANNOT access:             │
│  ❌ Financial Reports (finance)             │
│  ❌ IT Documentation (it)                   │
│  ❌ Board Minutes (executive)               │
│                                             │
└─────────────────────────────────────────────┘

​
Next Steps