Skip to main content

​
Role-Based Access Control

Roles are the primary mechanism for controlling which documents each user can access. When a user queries the AI, they only see answers from documents they have permission to access.

​
How It Works

  1. User sends request with roles in X-External-Roles header
  2. System builds access filter based on user’s roles
  3. Documents are filtered to only those matching user’s roles
  4. AI generates answer from accessible documents only

​
Key Concepts

​
Roles

A role is simply a string that represents a permission group:
  • hr - Human Resources team
  • finance - Finance department
  • manager - Management level
  • all-staff - Everyone in the company

​
Document ACLs

Each document (or folder) has an Access Control List specifying which roles can access it:
DocumentACL Roles
Employee Handbookall-staff
HR Policieshr
Financial Reportsfinance, executive
Management Guidelinesmanager, executive

​
Role Matching

A user can access a document if they have any of the document’s ACL roles: 
User Roles: ["hr", "manager"]

Employee Handbook (all-staff): ❌ No match
HR Policies (hr): ✅ Match - has "hr"
Financial Reports (finance, executive): ❌ No match
Management Guidelines (manager, executive): ✅ Match - has "manager"

​
Example Flow

​
Setup

  1. Partner uploads HR documents with aclRoles: ["hr"]
  2. Partner uploads company-wide docs with aclRoles: ["all-staff"]

​
Request

POST /api/ai/chat
X-External-Org-Id: acme
X-External-User-Id: alice
X-External-Roles: ["hr", "all-staff"]

{ "message": "What are the hiring procedures?" }

​
Result

Alice sees answers from:
  • HR documents (she has “hr” role)
  • Company-wide documents (she has “all-staff” role)
Alice does NOT see:
  • Finance documents
  • Executive documents

​
Wildcard Access

If a document has no ACL (empty roles), it’s accessible to everyone in the organization. This is the default for documents uploaded without specifying roles.

​
Next Steps