Permissions
Permission System
Cludz Storage uses a hierarchical permission system with three levels of access control. To manage permissions, open your drive and click folder settings that has a icon.
Access Types
Public Access
Folders marked as Public allow anyone to read files without authentication:
# No token required for public resources
curl -X GET "https://storage.cludz.net/storage/{uuid}/public-folder/image.jpg"
Private Access
Private folders require authentication and explicit permissions:
| Permission | Capabilities |
|---|---|
| Read | View and download files |
| Write | Upload and modify files (includes Read) |
| Delete | Remove files and folders (includes Read) |
Guest Permissions
Folders can grant guest access with configurable permissions:
| Setting | Description |
|---|---|
guest_can_read | Allow unauthenticated read |
guest_can_write | Allow unauthenticated upload |
guest_can_delete | Allow unauthenticated delete |
Permission Inheritance
Permissions are inherited from parent folders. If a subfolder doesn't have explicit permissions, it inherits from the nearest parent with defined access.
/storage/{uuid}/
├── public-photos/ ← Public (Read for all)
│ └── events/ ← Inherits Public access
│ └── party.jpg ← Accessible without token
├── private-docs/ ← Private
│ └── contracts/ ← Inherits Private access
User-Specific Access
Individual users can be granted access to specific folders:
| Permission Level | Read | Write | Delete |
|---|---|---|---|
| Read | ✓ | ✗ | ✗ |
| Write | ✓ | ✓ | ✗ |
| Delete | ✓ | ✗ | ✓ |
Quota Owner
Each folder can specify who the uploaded file quota counts against:
| Setting | Description |
|---|---|
owner | Storage owner's quota |
uploader | Uploading user's quota |
Sharing Status
When listing directories, folders include a sharingStatus field:
{
"name": "shared-folder",
"isDirectory": true,
"sharingStatus": "shared"
}
| Value | Description |
|---|---|
"public" | Folder is publicly accessible |
"shared" | Folder has user-specific access |
null | Private folder (owner only) |
Permission Checking
The API checks permissions in this order:
- Owner check - Storage owner has full access
- Storage token - Valid token grants configured access
- Folder permissions - Check folder-level access settings
- User access - Check user-specific folder_access entries
- Guest access - Check guest permission flags
- Parent inheritance - Check parent folders recursively
Error Responses
| Status | Message |
|---|---|
401 | Token required |
403 | Access denied |
403 | No read permission |
403 | No write permission |
403 | No delete permission |
Examples
Public Folder Access
// Public read - no token needed
const response = await fetch('https://storage.cludz.net/storage/{uuid}/public/');
const files = await response.json();
Authenticated Access
// Private read - token required
const response = await fetch('https://storage.cludz.net/storage/{uuid}/private/', {
headers: { 'Token': 'YOUR_STORAGE_TOKEN' }
});
Check Permissions Before Action
// Try to upload, handle permission errors
const response = await fetch('https://storage.cludz.net/storage/{uuid}/folder/', {
method: 'POST',
headers: { 'Token': 'YOUR_STORAGE_TOKEN' },
body: formData
});
if (response.status === 403) {
console.error('No write permission for this folder');
}