Skip to main content

​
Folder Permissions

This guide explains how to set and manage access control lists (ACLs) on documents and folders.

​
Document-Level ACLs

Every document can have its own ACL specifying which roles can access it.

​
Setting ACLs on Upload

Specify aclRoles when uploading: 
curl -X POST https://api.docbit.ai/api/documents/upload \
  -H "Authorization: ApiKey sk_..." \
  -H "X-External-Org-Id: acme" \
  -H "X-External-User-Id: admin" \
  -H "X-External-Roles: [\"admin\"]" \
  -F "[email protected]" \
  -F "aclRoles=hr"

​
Multiple Roles

A document can be accessible to multiple roles: 
# Accessible to both hr AND finance roles
-F "aclRoles=hr" \
-F "aclRoles=finance"
Or in code: 
await uploadDocument({
  file: hrFinanceReport,
  aclRoles: ['hr', 'finance']  // Either role grants access
});

​
No ACL = Public to Org

Documents uploaded without aclRoles are visible to everyone in the organization: 
# No aclRoles = all users in the org can access
curl -X POST .../documents/upload \
  -F "[email protected]"

​
Folder Paths

Organize documents into folders using folderPath: 
curl -X POST .../documents/upload \
  -F "[email protected]" \
  -F "folderPath=/hr/policies" \
  -F "aclRoles=hr"

​
Folder Structure Example

/                           (org root)
├── /hr/
│   ├── /hr/policies/       (aclRoles: hr)
│   └── /hr/templates/      (aclRoles: hr)
├── /finance/
│   ├── /finance/reports/   (aclRoles: finance, executive)
│   └── /finance/budgets/   (aclRoles: finance)
└── /company/
    └── /company/general/   (no ACL = everyone)

​
ACL Strategies

​
Strategy 1: Document-Level Only

Set ACLs on each document individually: 
// HR document
await upload({ file: hrDoc, aclRoles: ['hr'] });

// Finance document
await upload({ file: financeDoc, aclRoles: ['finance'] });

// Company-wide document
await upload({ file: handbook }); // No ACL
Pros: Fine-grained control Cons: Must set on every upload

​
Strategy 2: Folder-Based Convention

Use folder paths to organize by access level, then set consistent ACLs: 
async function uploadToFolder(file, folder) {
  const folderAcls = {
    '/hr/': ['hr'],
    '/finance/': ['finance'],
    '/executive/': ['executive'],
    '/company/': [] // Public
  };
  
  const aclRoles = folderAcls[folder] || [];
  
  await upload({
    file,
    folderPath: folder,
    aclRoles
  });
}

// Usage
await uploadToFolder(hrDoc, '/hr/');      // Gets 'hr' ACL
await uploadToFolder(financeDoc, '/finance/'); // Gets 'finance' ACL

​
Strategy 3: Department + Classification

Combine department and sensitivity level: 
function getAclRoles(department, classification) {
  const roles = [department]; // e.g., 'hr'
  
  if (classification === 'executive-only') {
    roles.push('executive');
    return roles; // hr + executive required? No - either grants access
  }
  
  if (classification === 'company-wide') {
    return ['all-staff']; // Override department restriction
  }
  
  return roles;
}

​
Access Resolution

Remember: A user needs any one of the document’s ACL roles to access it.
Document ACLUser RolesCan Access?
['hr']['hr', 'all-staff']✅ Yes (has ‘hr’)
['hr', 'finance']['finance']✅ Yes (has ‘finance’)
['executive']['hr', 'manager']❌ No (no ‘executive’)
[] (empty)['employee']✅ Yes (no ACL = public)

​
Bulk Uploads

When uploading many documents, set ACLs programmatically: 
const documents = [
  { file: 'hr-policy.pdf', department: 'hr' },
  { file: 'finance-report.pdf', department: 'finance' },
  { file: 'company-handbook.pdf', department: null } // Public
];

for (const doc of documents) {
  await upload({
    file: doc.file,
    folderPath: doc.department ? `/${doc.department}/` : '/company/',
    aclRoles: doc.department ? [doc.department] : []
  });
}

​
Changing ACLs

To update a document’s ACL, you currently need to:
  1. Delete the existing document
  2. Re-upload with new ACLs
We’re working on an API to update document ACLs without re-uploading. Contact support if this is a priority for your use case.

​
Best Practices

Design your folder hierarchy before uploading. It’s easier to maintain consistent ACLs with good organization.
Document your role names and use them consistently across uploads.
When in doubt, set explicit ACLs rather than leaving documents public.
Periodically review which documents have which ACLs.

​
Next Steps