Skip to main content

​
Roles

The X-External-Roles header specifies which roles a user has, controlling which documents they can access. This is the foundation of DocBit AI’s role-based access control (RBAC).

​
What are Roles?

Roles are strings that represent permission groups. When a user queries the AI, they only see answers from documents that match their roles.

​
How Roles Work

​
1. You Assign Roles to Documents

When uploading documents, specify which roles can access them: 
curl -X POST .../documents/upload \
  -F "[email protected]" \
  -F "aclRoles=hr"           # Only "hr" role can see this

​
2. You Pass User’s Roles in Requests

When a user queries, include their roles: 
X-External-Roles: ["hr", "all-staff"]

​
3. DocBit AI Filters Results

The AI only sees documents the user has access to:
DocumentACL RolesUser has hr, all-staffVisible?
HR Policyhr✅ Has hrYes
Handbookall-staff✅ Has all-staffYes
Financialsfinance❌ No matchNo

​
Role Format

Pass roles as a JSON array in the header: 
X-External-Roles: ["role1", "role2", "role3"]
Or as comma-separated values: 
X-External-Roles: role1,role2,role3

​
Requirements

  • At least one role required - Empty arrays are rejected
  • Case-sensitive - HR and hr are different roles
  • No special characters needed - Use simple strings

​
Common Role Patterns

​
Department-Based

hr          - HR team
finance     - Finance team
engineering - Engineering team
all-staff   - Everyone

​
Hierarchy-Based

employee    - All employees
manager     - Managers
director    - Directors
executive   - C-suite

​
Project-Based

project-alpha  - Alpha team
project-beta   - Beta team
project-lead   - All leads

​
Access Levels

public       - Public info
internal     - Internal only
confidential - Restricted

​
Roles vs Document ACLs

ConceptWhat it isWho sets it
User RolesPermissions the user hasYou, via X-External-Roles
Document ACLRoles required to accessYou, when uploading (aclRoles)
A user can access a document if they have any role in the document’s ACL.

​
Dynamic Role Assignment

You control roles at request time, enabling dynamic access: 
function getRolesForUser(user) {
  const roles = ['all-staff']; // Everyone gets this
  
  if (user.department === 'hr') roles.push('hr');
  if (user.isManager) roles.push('manager');
  if (user.projects) roles.push(...user.projects);
  
  return roles;
}

// Use in request
const roles = getRolesForUser(currentUser);
await chat({
  headers: {
    'X-External-Roles': JSON.stringify(roles)
  }
});

​
Wildcard Access

Documents uploaded without aclRoles are accessible to everyone in the organization: 
# No aclRoles = everyone can see it
curl -X POST .../documents/upload \
  -F "[email protected]"
To restrict access, always specify aclRoles when uploading.

​
Best Practices

Start with a small set of roles. You can always add more later.
Stick to lowercase, hyphenated names: project-alpha, not Project Alpha.
If you have user groups in your system, use the same names as roles.
Only pass roles the user actually has. Don’t give everyone admin access.
Consider an all-staff or employee role for company-wide documents.

​
Next Steps