Sharing Documents

Learn how to share documents with team members, set permissions, and manage access.

---

Quick Share

Share a document with a team member:

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"
  }'

---

Sharing Methods

Share with User

Share a document with a specific user:

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"
  }'

Response:

{
  "share_id": "share_abc123",
  "document_id": "doc_abc123",
  "user_id": "user_xyz789",
  "permission": "view",
  "created_at": "2025-12-16T10:30:00Z"
}

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_xyz789",
    "permission": "edit"
  }'

Create Share Link

Create a shareable link (Pro+):

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",
    "password": "optional-password"
  }'

Response:

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

---

Permissions

Permission Levels

Permission	Can View	Can Download	Can Edit	Can Delete
view
download
edit
admin

Set 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"
  }'

---

Code Examples

Python - Share Documents

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):
        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
        }
        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 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']}")

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

# Revoke share
sharing.revoke_share("share_abc123")

JavaScript - Share Documents

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) {
    const expiresAt = new Date();
    expiresAt.setDate(expiresAt.getDate() + expiresDays);
    
    const response = await fetch(`${this.baseURL}/documents/${documentId}/share-link`, {
      method: 'POST',
      headers: { ...this.headers, 'Content-Type': 'application/json' },
      body: JSON.stringify({
        permission,
        expires_at: expiresAt.toISOString()
      })
    });
    return response.json();
  }
  
  async listShares(documentId) {
    const response = await fetch(`${this.baseURL}/documents/${documentId}/shares`, {
      headers: this.headers
    });
    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);

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

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

---

Managing Shares

List All Shares

Get all shares for a document:

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

Response:

{
  "shares": [
    {
      "share_id": "share_abc123",
      "user_id": "user_xyz789",
      "user_name": "John Doe",
      "permission": "view",
      "created_at": "2025-12-16T10:30:00Z"
    },
    {
      "share_id": "share_def456",
      "workspace_id": "workspace_xyz",
      "workspace_name": "Legal Team",
      "permission": "edit",
      "created_at": "2025-12-15T14:20:00Z"
    }
  ]
}

Update Permission

Change permission level:

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

Remove access:

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

---

Share Links

Create Share Link

Generate a shareable 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"
  }'

Password Protection

Add password to 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",
    "password": "secure-password-123"
  }'

Revoke Share Link

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

---

Best Practices

Permission Levels

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

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 than individual shares
3. Set expiration - Especially for share links
4. Audit regularly - Review who has access

---

Next Steps

• Collaboration Guide - Team collaboration features
• Workspaces Guide - Organize team documents
• API Reference - Complete sharing API documentation

---

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