# Access Management

div
strong
🔨 In Development
 — This section is still being developed and may change.


Learn how to control who can view, use, and edit assistants in your organization using Freddy's flexible access management system.

## Overview

Freddy provides two complementary access control systems that work together:

1. **Legacy System** - Simple, broad access control using modes and departments
2. **Granular System** - Fine-grained control using individual users and roles


Both systems work together, with the creator (`createdBy`) always having full owner access.

## Legacy Access System

The legacy system provides simple, organization-wide access control.

### Access Mode

The `accessMode` field defines the overall visibility level:

| Mode | Description | Who Can Access |
|  --- | --- | --- |
| `private` | Only creator | Creator only |
| `restricted` | Specific users | Users in `accessUsers` list |
| `department` | Department members | Users in departments listed in `accessDepartments` |
| `organization` | All org members | Everyone in the organization |
| `global` | Cross-organization | Users across multiple organizations |
| `public` | Anyone | Anyone with the link |


### Access Departments

When `accessMode` is set to `department`, the `accessDepartments` array specifies which departments have access:


```json
{
  "accessMode": "department",
  "accessDepartments": ["Engineering", "Sales", "Marketing"]
}
```

### Access Users

When `accessMode` is set to `restricted`, the `accessUsers` array specifies which individual users can view/use the assistant:


```json
{
  "accessMode": "restricted",
  "accessUsers": ["uid_123", "uid_456", "uid_789"]
}
```

## Granular Access System

The granular system provides fine-grained control over who can edit and view assistants, independent of the legacy access mode.

### Edit Permissions

#### By User

The `editableByUsers` array grants edit permissions to specific users, regardless of access mode:


```json
{
  "editableByUsers": ["uid_test1", "uid_test2"]
}
```

**Note:** The creator is always included implicitly and doesn't need to be in this list.

#### By Role

The `editableByRoles` array grants edit permissions to users with specific roles:


```json
{
  "editableByRoles": ["admin", "manager", "developer"]
}
```

**Common roles:**

- `admin` - Organization administrators
- `manager` - Team managers
- `member` - Regular organization members
- `developer` - Technical team members
- `viewer` - Read-only users


### View Permissions

#### By User

The `visibleInChatToUsers` array controls which users can see the assistant in chat and configuration interfaces:


```json
{
  "visibleInChatToUsers": ["uid_test3", "uid_test4"]
}
```

This controls **UI visibility**, not just access permissions.

#### By Role

The `visibleToRoles` array grants view permissions to users with specific roles:


```json
{
  "visibleToRoles": ["member", "viewer", "admin"]
}
```

## How Access Control Works

When a user tries to access an assistant, Freddy checks permissions in this order:

### For Viewing/Using an Assistant

1. ✅ **Creator Check** - If user is the creator (`createdBy`), grant access
2. ✅ **Role-Based View** - If user's role is in `visibleToRoles`, grant access
3. ✅ **User-Based View** - If user ID is in `visibleInChatToUsers`, grant access
4. ✅ **Legacy Access Mode** - Check based on `accessMode`:
  - `private` → Only creator
  - `restricted` → Check `accessUsers` list
  - `department` → Check if user is in any department from `accessDepartments`
  - `organization` → All organization members
  - `public` → Everyone


### For Editing an Assistant

1. ✅ **Creator Check** - If user is the creator, grant edit access
2. ✅ **Role-Based Edit** - If user's role is in `editableByRoles`, grant edit access
3. ✅ **User-Based Edit** - If user ID is in `editableByUsers`, grant edit access
4. ❌ Otherwise, deny edit access


## Common Patterns

### Pattern 1: Organization-Wide with Admin Editing

Everyone can use it, only admins can edit:


```json
{
  "accessMode": "organization",
  "editableByRoles": ["admin"]
}
```

### Pattern 2: Department-Specific with Manager Editing

Department members can use it, managers can edit:


```json
{
  "accessMode": "department",
  "accessDepartments": ["Engineering"],
  "editableByRoles": ["admin", "manager"]
}
```

### Pattern 3: Private with Specific Collaborators

Only creator and specific users can access and edit:


```json
{
  "accessMode": "private",
  "editableByUsers": ["uid_collaborator1", "uid_collaborator2"],
  "visibleInChatToUsers": ["uid_collaborator1", "uid_collaborator2"]
}
```

### Pattern 4: Public View, Restricted Edit

Anyone can use it, only specific users can edit:


```json
{
  "accessMode": "public",
  "editableByUsers": ["uid_maintainer1"],
  "editableByRoles": ["admin"]
}
```

### Pattern 5: Complex Multi-Level Access

Combine legacy and granular systems for maximum flexibility:


```json
{
  "accessMode": "department",
  "accessDepartments": ["Engineering", "Product"],
  "editableByRoles": ["admin", "manager"],
  "editableByUsers": ["uid_lead_engineer"],
  "visibleToRoles": ["member", "viewer"],
  "visibleInChatToUsers": ["uid_external_consultant"]
}
```

## Best Practices

### 1. Start Simple

Use the legacy `accessMode` system for most cases:

- `organization` for company-wide assistants
- `department` for team-specific assistants
- `private` for personal assistants


### 2. Add Granular Controls When Needed

Use the granular system when you need:

- Specific users to edit a shared assistant
- Role-based permissions across departments
- Fine-grained UI visibility control


### 3. Document Your Access Strategy

Add metadata to track why specific permissions were granted:


```json
{
  "accessMode": "department",
  "accessDepartments": ["Sales"],
  "editableByRoles": ["admin", "manager"],
  "metadata": {
    "access_reason": "Sales team assistant with manager oversight",
    "last_review": "2025-01-15"
  }
}
```

### 4. Regular Access Audits

Periodically review:

- Who has edit permissions (`editableByUsers`, `editableByRoles`)
- Unused assistants with broad access
- Assistants with complex permission combinations


### 5. Use Roles Over Individual Users

Prefer `editableByRoles` and `visibleToRoles` over individual user lists for easier maintenance:


```json
// ✅ Good - Uses roles
{
  "editableByRoles": ["admin", "manager"]
}

// ❌ Harder to maintain - Individual users
{
  "editableByUsers": ["uid_1", "uid_2", "uid_3", "uid_4", "uid_5"]
}
```

## API Examples

### Creating an Assistant with Access Control


```bash
curl "https://api.freddy.aitronos.com/v1/assistants" \
  -H "Authorization: Bearer $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales Assistant",
    "model": "gpt-4o",
    "instructions": "Help with sales inquiries",
    "accessMode": "department",
    "accessDepartments": ["Sales"],
    "editableByRoles": ["admin", "manager"]
  }'
```

### Updating Access Permissions


```bash
curl -X PUT "https://api.freddy.aitronos.com/v1/assistants/asst_abc123" \
  -H "Authorization: Bearer $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "editableByUsers": ["uid_new_collaborator"],
    "visibleToRoles": ["member", "viewer", "admin"]
  }'
```

## Related

- [Assistant object](/docs/api-reference/objects/assistant-object) - Complete field reference
- [Create assistant](/docs/api-reference/assistants/create) - Create with access control
- [Update assistant](/docs/api-reference/assistants/update) - Modify permissions
- [List assistants](/docs/api-reference/assistants/list) - Filter by access mode