ACL and User Management

Papr Memory provides enterprise-grade security through a comprehensive Access Control List (ACL) system and robust multi-tenancy support. This page explains how to manage access control and implement multi-tenant isolation.

User Management and Access Control

Papr Memory integrates user management with its access control system, allowing you to create users and manage memories for specific users within your security framework.

Creating and Managing Users

# Create a new user
user = client.user.create(
    external_id="user123",
    email="user@example.com",
    metadata={
        "name": "John Doe",
        "role": "developer",
        "team": "Engineering"
    },
    type="developerUser"  # Options: "developerUser", "user", "agent"
)

# Retrieve user details
user_details = client.user.get(user.user_id)

# Update user information
updated_user = client.user.update(
    user_id=user.user_id,
    email="updated.user@example.com",
    metadata={
        "name": "John Doe",
        "role": "senior developer",
        "team": "Engineering"
    }
)

# Delete a user if needed
delete_response = client.user.delete(user.user_id)

Managing User-Specific Memories with Access Control

Access control is implemented through memory metadata fields that specify which users, workspaces, or roles have read or write access.

# Add memory with specific user permissions
memory = client.memory.add(
    content="Confidential project notes",
    type="text",
    metadata={
        "user_id": user.user_id,
        "topics": "project, confidential, planning",
        "user_read_access": [user.user_id, "admin_user_id"],
        "user_write_access": [user.user_id]
    }
)

# Search memories with user context
results = client.memory.search(
    query="Find confidential project notes",
    metadata={
        "user_id": user.user_id  # Limit to this user's content
    }
)

User-Specific Batch Operations

# Batch add memories for a specific user
response = client.memory.add_batch(
    memories=[
        {
            "content": "Meeting notes from team standup",
            "metadata": {"user_id": user.user_id, "topics": "meeting, standup"}
        },
        {
            "content": "Action items from planning session",
            "metadata": {"user_id": user.user_id, "topics": "planning, tasks"}
        }
    ]
)

Papr Memory allows sharing memories between users within a workspace or organization. This can be achieved in several ways:

Public vs Private Memories

By default, memories can be scoped by:

Private to a user: Only accessible to the specific user
Shared with specific users: Accessible to a defined list of users
Available to a workspace: Accessible to all users in a workspace
Organization-wide: Available across the entire organization

# Create a private memory (only for user_123)
private_memory = client.memory.add(
    content="My personal notes",
    type="text",
    metadata={
        "user_id": "user_123",
        "user_read_access": ["user_123"],
        "user_write_access": ["user_123"]
    }
)

# Create a memory shared with specific users
shared_memory = client.memory.add(
    content="Project plan for Team Alpha",
    type="text",
    metadata={
        "user_id": "user_123",
        "user_read_access": ["user_123", "user_456", "user_789"],
        "user_write_access": ["user_123", "user_456"]
    }
)

# Create a workspace-accessible memory
workspace_memory = client.memory.add(
    content="Company-wide announcement",
    type="text",
    metadata={
        "user_id": "user_123",
        "workspace_id": "workspace_001",
        "workspace_read_access": ["workspace_001"]
    }
)

# Create an organization-wide memory
org_memory = client.memory.add(
    content="Quarterly results",
    type="text",
    metadata={
        "user_id": "user_123",
        "role_read_access": ["all_employees"]  # Using a role that all employees have
    }
)

You can change the sharing settings of a memory by updating its metadata:

# Update memory to add additional user access
updated_memory = client.memory.update(
    memory_id="mem_123",
    metadata={
        "user_read_access": ["user_123", "user_456", "user_789", "user_new"],
        "user_write_access": ["user_123", "user_new"]
    }
)

# Change a private memory to be workspace-accessible
public_memory = client.memory.update(
    memory_id="mem_private",
    metadata={
        "workspace_read_access": ["workspace_001"],
        "role_read_access": ["manager", "developer"]
    }
)

Searching Shared Memories

When searching, you can access all memories shared with you, including those created by other users:

# Search accessible memories including those shared by others
shared_results = client.memory.search(
    query="Project plan",
    # No user_id filter means search all accessible memories
)

# Search within a specific workspace
workspace_results = client.memory.search(
    query="Company announcement",
    metadata={
        "workspace_id": "workspace_001"
    }
)

Workspace-Based Multi-Tenancy

In the Papr API, multi-tenancy is implemented primarily through the workspace concept. Each memory can be associated with a workspace, and access controls can be applied at the workspace level.

Access Control via Metadata

Access control is implemented through metadata fields in the memory objects:

{
  "metadata": {
    "user_id": "user_123",
    "workspace_id": "workspace_789",
    "user_read_access": ["user_123", "user_456"],
    "user_write_access": ["user_123"],
    "workspace_read_access": ["workspace_789"],
    "workspace_write_access": [],
    "role_read_access": ["admin", "developer"],
    "role_write_access": ["admin"]
  }
}

Access Control Lists (ACL)

Permission Levels Through Metadata

User-Level Permissions

{
  "metadata": {
    "user_read_access": ["user_123", "user_456"],
    "user_write_access": ["user_123"]
  }
}

Workspace-Level Permissions

{
  "metadata": {
    "workspace_read_access": ["workspace_789", "workspace_012"],
    "workspace_write_access": ["workspace_789"]
  }
}

Role-Level Permissions

{
  "metadata": {
    "role_read_access": ["admin", "editor", "viewer"],
    "role_write_access": ["admin", "editor"]
  }
}

Role-Based Access Control

While the API does not provide explicit endpoints for role management, you can implement role-based access control through the metadata fields. Common roles might include:

Admin: Full access to create, read, update and delete memories
Editor: Can read and update memories but not delete them
Viewer: Read-only access to memories

These roles are implemented by consistently using the same role identifiers in the role_read_access and role_write_access metadata fields.

Implementation

Authentication

The Papr API supports multiple authentication methods:

# Initialize client with API key
client = PaprMemory(api_key="your_api_key")

# Or initialize with bearer token
client = PaprMemory(bearer_token="your_bearer_token")

# Or initialize with session token
client = PaprMemory(session_token="your_session_token")

Implementing Access Control

# Create memory with access control
memory = client.memory.add(
    content="Quarterly financial report",
    type="text",
    metadata={
        "workspace_id": "finance_workspace",
        "topics": "finance, quarterly, confidential",
        "user_read_access": ["finance_team_lead", "cfo", "ceo"],
        "user_write_access": ["finance_team_lead"],
        "role_read_access": ["finance_department", "executive"],
        "role_write_access": ["finance_department_lead"]
    }
)

# Filter memories by access control in search
results = client.memory.search(
    query="Find quarterly financial reports",
    metadata={
        "user_id": "finance_team_lead",
        "workspace_id": "finance_workspace"
    }
)

Security Features

Data Isolation

Isolation through metadata-based access control
Separate metadata filtering for searches
Memory-level access restrictions

Access Controls

Fine-grained permissions through metadata
User, workspace, and role-based access
Extensible metadata attributes

Audit Logging

Access logs through memory interactions
Search and retrieval tracking
Content modification history

Compliance

GDPR compliance through metadata filtering
Data retention controls
Access control for regulatory requirements

Best Practices

Access Control Design
- Establish consistent naming conventions for roles
- Create logical workspace structures
- Document access control schema
- Regularly review access patterns
User Management
- Use descriptive external IDs
- Add comprehensive user metadata
- Maintain up-to-date user records
- Plan for user lifecycle management
Security
- Rotate API keys regularly
- Apply principle of least privilege in access controls
- Monitor access patterns
- Implement rate limiting
Compliance
- Document data flows
- Set retention policies
- Implement comprehensive metadata
- Regular compliance reviews

Next Steps

Explore Authentication Guide