Sharing & Permissions

Learn how to share documents and manage permissions for team collaboration.

---

Overview

Archivus provides flexible sharing and permission management:

• User sharing - Share with specific users
• Workspace sharing - Share with entire workspaces
• Share links - Create shareable links (Pro+)
• Permission levels - Control what users can do

---

Permission Levels

Permission Types

Permission	View	Download	Edit	Delete	Share
view
download
edit
admin

---

Share with User

Basic Share

curl -X POST https://api.archivus.app/api/v1/documents/doc_abc123/share \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Tenant-Subdomain: your-tenant" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_xyz789",
    "permission": "view"
  }'

Share with Permission

curl -X POST https://api.archivus.app/api/v1/documents/doc_abc123/share \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Tenant-Subdomain: your-tenant" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_xyz789",
    "permission": "edit"
  }'

---

Share with Workspace

Share a document with all members of a workspace:

curl -X POST https://api.archivus.app/api/v1/documents/doc_abc123/share \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Tenant-Subdomain: your-tenant" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "workspace_abc123",
    "permission": "view"
  }'

---

Share Links (Pro+)

Create Share Link

curl -X POST https://api.archivus.app/api/v1/documents/doc_abc123/share-link \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Tenant-Subdomain: your-tenant" \
  -H "Content-Type: application/json" \
  -d '{
    "permission": "view",
    "expires_at": "2025-12-31T23:59:59Z"
  }'

Response:

{
  "share_link": "https://archivus.app/shared/doc_abc123?token=xyz789",
  "expires_at": "2025-12-31T23:59:59Z",
  "permission": "view"
}

Password-Protected Link

curl -X POST https://api.archivus.app/api/v1/documents/doc_abc123/share-link \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Tenant-Subdomain: your-tenant" \
  -H "Content-Type: application/json" \
  -d '{
    "permission": "view",
    "password": "secure-password-123",
    "expires_at": "2025-12-31T23:59:59Z"
  }'

---

Code Examples

Python - Sharing & Permissions

import requests
from datetime import datetime, timedelta

class ArchivusSharing:
    def __init__(self, api_key, tenant):
        self.api_key = api_key
        self.tenant = tenant
        self.base_url = "https://api.archivus.app/api/v1"
        self.headers = {
            "Authorization": f"Bearer {api_key}",
            "X-Tenant-Subdomain": tenant
        }
    
    def share_with_user(self, document_id, user_id, permission="view"):
        url = f"{self.base_url}/documents/{document_id}/share"
        data = {
            "user_id": user_id,
            "permission": permission
        }
        response = requests.post(url, headers=self.headers, json=data)
        return response.json()
    
    def share_with_workspace(self, document_id, workspace_id, permission="view"):
        url = f"{self.base_url}/documents/{document_id}/share"
        data = {
            "workspace_id": workspace_id,
            "permission": permission
        }
        response = requests.post(url, headers=self.headers, json=data)
        return response.json()
    
    def create_share_link(self, document_id, permission="view", expires_days=30, password=None):
        url = f"{self.base_url}/documents/{document_id}/share-link"
        expires_at = (datetime.now() + timedelta(days=expires_days)).isoformat()
        data = {
            "permission": permission,
            "expires_at": expires_at
        }
        if password:
            data["password"] = password
        
        response = requests.post(url, headers=self.headers, json=data)
        return response.json()
    
    def list_shares(self, document_id):
        url = f"{self.base_url}/documents/{document_id}/shares"
        response = requests.get(url, headers=self.headers)
        return response.json()
    
    def update_permission(self, share_id, permission):
        url = f"{self.base_url}/shares/{share_id}"
        data = {"permission": permission}
        response = requests.put(url, headers=self.headers, json=data)
        return response.json()
    
    def revoke_share(self, share_id):
        url = f"{self.base_url}/shares/{share_id}"
        response = requests.delete(url, headers=self.headers)
        return response.status_code == 200

# Usage
sharing = ArchivusSharing("YOUR_API_KEY", "your-tenant")

# Share with user
share = sharing.share_with_user("doc_abc123", "user_xyz789", "view")

# Share with workspace
share = sharing.share_with_workspace("doc_abc123", "workspace_xyz", "edit")

# Create share link
link = sharing.create_share_link("doc_abc123", "view", expires_days=7)
print(f"Share link: {link['share_link']}")

# Create password-protected link
secure_link = sharing.create_share_link(
    "doc_abc123",
    "view",
    expires_days=7,
    password="secure-password"
)

# List all shares
shares = sharing.list_shares("doc_abc123")

# Update permission
sharing.update_permission("share_abc123", "edit")

# Revoke share
sharing.revoke_share("share_abc123")

JavaScript - Sharing & Permissions

class ArchivusSharing {
  constructor(apiKey, tenant) {
    this.apiKey = apiKey;
    this.tenant = tenant;
    this.baseURL = 'https://api.archivus.app/api/v1';
    this.headers = {
      'Authorization': `Bearer ${apiKey}`,
      'X-Tenant-Subdomain': tenant
    };
  }
  
  async shareWithUser(documentId, userId, permission = 'view') {
    const response = await fetch(`${this.baseURL}/documents/${documentId}/share`, {
      method: 'POST',
      headers: { ...this.headers, 'Content-Type': 'application/json' },
      body: JSON.stringify({ user_id: userId, permission })
    });
    return response.json();
  }
  
  async shareWithWorkspace(documentId, workspaceId, permission = 'view') {
    const response = await fetch(`${this.baseURL}/documents/${documentId}/share`, {
      method: 'POST',
      headers: { ...this.headers, 'Content-Type': 'application/json' },
      body: JSON.stringify({ workspace_id: workspaceId, permission })
    });
    return response.json();
  }
  
  async createShareLink(documentId, permission = 'view', expiresDays = 30, password = null) {
    const expiresAt = new Date();
    expiresAt.setDate(expiresAt.getDate() + expiresDays);
    
    const data = {
      permission,
      expires_at: expiresAt.toISOString()
    };
    if (password) data.password = password;
    
    const response = await fetch(`${this.baseURL}/documents/${documentId}/share-link`, {
      method: 'POST',
      headers: { ...this.headers, 'Content-Type': 'application/json' },
      body: JSON.stringify(data)
    });
    return response.json();
  }
  
  async listShares(documentId) {
    const response = await fetch(`${this.baseURL}/documents/${documentId}/shares`, {
      headers: this.headers
    });
    return response.json();
  }
  
  async updatePermission(shareId, permission) {
    const response = await fetch(`${this.baseURL}/shares/${shareId}`, {
      method: 'PUT',
      headers: { ...this.headers, 'Content-Type': 'application/json' },
      body: JSON.stringify({ permission })
    });
    return response.json();
  }
  
  async revokeShare(shareId) {
    const response = await fetch(`${this.baseURL}/shares/${shareId}`, {
      method: 'DELETE',
      headers: this.headers
    });
    return response.ok;
  }
}

// Usage
const sharing = new ArchivusSharing('YOUR_API_KEY', 'your-tenant');

// Share with user
const share = await sharing.shareWithUser('doc_abc123', 'user_xyz789', 'view');

// Share with workspace
const workspaceShare = await sharing.shareWithWorkspace('doc_abc123', 'workspace_xyz', 'edit');

// Create share link
const link = await sharing.createShareLink('doc_abc123', 'view', 7);
console.log('Share link:', link.share_link);

// Create password-protected link
const secureLink = await sharing.createShareLink('doc_abc123', 'view', 7, 'secure-password');

// List all shares
const shares = await sharing.listShares('doc_abc123');

// Update permission
await sharing.updatePermission('share_abc123', 'edit');

// Revoke share
await sharing.revokeShare('share_abc123');

---

Manage Shares

List All Shares

curl https://api.archivus.app/api/v1/documents/doc_abc123/shares \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Tenant-Subdomain: your-tenant"

Update Permission

curl -X PUT https://api.archivus.app/api/v1/shares/share_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Tenant-Subdomain: your-tenant" \
  -H "Content-Type: application/json" \
  -d '{
    "permission": "edit"
  }'

Revoke Share

curl -X DELETE https://api.archivus.app/api/v1/shares/share_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Tenant-Subdomain: your-tenant"

---

Best Practices

Permission Strategy

1. Start with view - Grant minimum necessary access
2. Upgrade as needed - Increase permissions when required
3. Use workspaces - Better than individual shares for teams
4. Review regularly - Audit shares periodically

Share Links

1. Set expiration - Always set expiration dates
2. Use passwords - For sensitive documents
3. Monitor usage - Track who accesses shared links
4. Revoke unused - Remove links no longer needed

Security

1. Limit access - Only share with necessary people
2. Use workspaces - Better security than individual shares
3. Set expiration - Especially for share links
4. Audit regularly - Review who has access

---

Next Steps

• Workspaces Guide - Organize team documents
• API Reference - Complete sharing API documentation

---

Questions? Check the FAQ or contact support@ubiship.com