> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lighton.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Identity & Access Management Overview

> Understanding how users, groups, and workspaces control access in Paradigm

## Understanding Paradigm's Access Control Architecture

Paradigm's security model is built on a three-tier hierarchy that controls who can access what content:

```
👤 Users (Identity)
    ↓
👥 Groups (Grouping)
    ↓
📁 Workspaces (Content Scope)
    ↓
📄 Documents (Actual Content)
```

This architecture ensures that access control is:

* **Scalable**: Manage hundreds of users through group memberships
* **Secure**: Clear boundaries between different content scopes
* **Flexible**: Fine-grained control from company-wide to private access
* **Auditable**: Track who has access to what and when

***

## The Three Core Components

### 1. Users - Your Identity Layer

**Users** are individual accounts in Paradigm. Each user:

* Has a unique email and authentication
* Belongs to exactly **one company**
* Can be assigned multiple **roles** that define their permissions
* Automatically gets a **Private Group** for personal workspace access

<Info>
  **Key Concept**: Users never directly access documents. Access is always mediated through group membership and workspace associations.
</Info>

**Learn more**: [User Management →](/en/administration/iam/user-management/user-roles)

***

### 2. Groups - Your Grouping Layer

**Groups** are the central mechanism for organizing users and controlling access. There are three types:

#### Company Group (Automatic)

* **Automatically created** for each company
* **All users** in the company are automatically members
* Controls access to company-wide workspaces
* Cannot be deleted or modified

#### Custom Groups

* **Manually created** by administrators
* Used for departments, projects, or any grouping you need
* Members are explicitly assigned
* Example: "Engineering Group", "Sales EMEA", "Project Phoenix"

#### Private Groups (Automatic)

* **Automatically created** for each user
* Only that user is a member
* Controls access to that user's private workspace
* Cannot be deleted or modified

<Warning>
  **Critical Understanding**: Groups are how you control workspace access. When you add a group to a workspace, all group members get access to that workspace's documents.
</Warning>

**Learn more**: [Group Management →](/en/administration/iam/group-management/understanding-groups)

***

### 3. Workspaces - Your Content Scope Layer

**Workspaces** are containers that organize documents and control access through group membership. Each workspace:

* Contains a **Collection** of documents
* Has one or more **Groups** as members
* Defines the **scope** of document accessibility
* Can be linked to external data sources

There are three workspace types that mirror the three group types:

| Workspace Type | Linked Group    | Access Level           | Use Case                  |
| -------------- | --------------- | ---------------------- | ------------------------- |
| **Company**    | Company Group   | All company users      | HR policies, general docs |
| **Custom**     | Custom Group(s) | Specific group members | Projects, departments     |
| **Private**    | Private Group   | Individual user only   | Personal notes, drafts    |

<Info>
  **The Key Relationship**: Workspace access is determined by group membership. If you're a member of a group that's associated with a workspace, you can access that workspace's documents.
</Info>

**Learn more**: [Workspace Fundamentals →](/en/administration/knowledge-management/workspaces/understanding-workspaces)

***

## How Access Control Works in Practice

### Example 1: Department Access

```
Scenario: Engineering group needs access to technical documentation

1. Create Custom Group: "Engineering Group"
2. Add engineers as group members
3. Create Custom Workspace: "Engineering - Technical Docs"
4. Associate "Engineering Group" with the workspace
5. Upload documents to the workspace

Result: All engineering group members can now access these documents
```

### Example 2: Project-Based Access

```
Scenario: Cross-functional project needs temporary access

1. Create Custom Group: "Project Phoenix"
2. Add members from different departments
3. Create Custom Workspace: "Project Phoenix - Documentation"
4. Associate "Project Phoenix" group with workspace
5. When project ends, remove group members

Result: Only project group members have access during project lifecycle
```

### Example 3: Company-Wide Policy

```
Scenario: HR policies need to be accessible to everyone

1. Use existing Company Group (automatic)
2. Use existing Company Workspace (or create new company workspace)
3. Upload HR documents to company workspace

Result: All company employees automatically have access
```

***

## Permission Model

### User Roles Define Actions

User roles control **what actions** a user can perform:

| Role                 | Create Workspaces | Upload Documents | Manage Members  | View All Docs   |
| -------------------- | ----------------- | ---------------- | --------------- | --------------- |
| **Admin**            | ✅ All companies   | ✅ All Workspaces | ✅ All companies | ✅ All companies |
| **SysAdmin**         | ✅ All companies   | ❌                | ✅ All companies | ✅ Where member  |
| **Account Manager**  | ✅ All companies   | ❌                | ✅ All companies | ✅ Where member  |
| **Company Admin**    | ✅ Own company     | ❌                | ✅ Own company   | ✅ Where member  |
| **Document Manager** | ❌                 | ✅ Where member   | ❌               | ❌               |
| **Standard User**    | ❌                 | ❌                | ❌               | ❌               |

### Group Membership Defines Scope

Group membership controls **what content** a user can access:

```
User's Accessible Documents = 
  Documents in workspaces whose member groups include the user
```

<Warning>
  **Important**: All roles can only see documents in workspaces where they're a member (directly or through groups), unless they explicitly have cross-company access.
</Warning>

***

## Security Principles

### 1. Principle of Least Privilege

Users should only have access to:

* The **minimum role** needed to perform their job
* The **minimum group memberships** needed for their work
* The **minimum workspaces** needed for their projects

### 2. Segregation of Duties

Different roles have different capabilities:

* **Admins** manage structure (users, groups, workspaces)
* **Document Managers** manage content (upload, delete documents)
* **Users** consume content (read, query documents)

### 3. Audit Trail

All access-related events are logged:

* User creation and role changes
* Group membership changes
* Workspace access attempts
* Document uploads and deletions

***

## Common Access Patterns

### Pattern 1: Departmental Structure

```
Marketing (Custom Group)
  └── Marketing Workspace
      └── Campaign docs, brand assets

Sales (Custom Group)
  └── Sales Workspace
      └── Playbooks, proposals

Engineering (Custom Group)
  └── Engineering Workspace
      └── Technical docs, specs
```

### Pattern 2: Project-Based Structure

```
Project Alpha Group (Custom Group)
  └── Project Alpha Workspace
      └── All project documentation

Project Beta Group (Custom Group)
  └── Project Beta Workspace
      └── All project documentation
```

### Pattern 3: Mixed Structure (Recommended)

```
Company Group
  └── Company Workspace → HR policies, general info

Engineering Group
  └── Engineering Workspace → Shared technical docs

Project Phoenix Group
  └── Project Phoenix Workspace → Project-specific docs

Each User's Private Group
  └── Each User's Private Workspace → Personal drafts
```

***

## Decision Framework

### When to Create a New Group

✅ Create a new custom group when:

* A distinct group needs access to specific content
* The group will persist over time
* Members need to collaborate on shared documents

❌ Don't create a group if:

* It's for a one-time document share (use existing group)
* Only one person needs access (use private workspace)
* Everyone in company needs access (use company group)

### When to Create a New Workspace

✅ Create a new workspace when:

* Content has different access requirements
* Documents form a coherent knowledge domain
* You need to isolate sensitive information

❌ Don't create a workspace if:

* Documents can fit in existing workspace
* Same group needs access
* It's just for organization (use folders instead)

***

## Next Steps

Now that you understand the architecture, dive into each component:

<CardGroup cols={2}>
  <Card title="User Management" icon="users" href="/en/administration/iam/user-management/user-roles">
    Create users, assign roles, and manage permissions
  </Card>

  <Card title="Group Management" icon="user-group" href="/en/administration/iam/group-management/understanding-groups">
    Organize users into groups for access control
  </Card>

  <Card title="Workspace Management" icon="folder" href="/en/administration/knowledge-management/workspaces/understanding-workspaces">
    Create and manage content containers
  </Card>

  <Card title="Document Access Control" icon="lock" href="/en/administration/knowledge-management/documents/document-access-management">
    Understand how documents are secured
  </Card>
</CardGroup>

***

## Quick Reference

### Access Control Flow

```mermaid theme={null}
graph TD
    A[User logs in] --> B{What groups am I in?}
    B --> C[Company Group - automatic]
    B --> D[Custom Groups - explicit]
    B --> E[Private Group - automatic]
    
    C --> F[Company Workspaces]
    D --> G[Custom Workspaces]
    E --> H[Private Workspace]
    
    F --> I[Can access these documents]
    G --> I
    H --> I
```

### Key Relationships

* **1 User** → **1 Company** (fixed)
* **1 User** → **Many Groups** (flexible)
* **1 Group** → **Many Workspaces** (flexible)
* **1 Workspace** → **Many Groups** (flexible)
* **1 Workspace** → **1 Collection** (fixed)
* **1 Collection** → **Many Documents** (flexible)