# Assistant Access Management

Control who can view, edit, and manage your assistants with Freddy's granular access control system.

## Access Levels

Assistants use a hierarchical three-tier permission model:

| Level | Permissions | Can Delete |
|  --- | --- | --- |
| **Owner** | Full control: view, edit, delete, manage access | ✅ Yes |
| **Edit** | Can modify assistant configuration and settings | ❌ No |
| **View** | Read-only access to assistant details | ❌ No |
| **None** | No access to the assistant | ❌ No |


## How Access is Determined

Access is evaluated in priority order. The first matching rule determines the user's access level:

### 1. Creator = Owner

The user who created the assistant automatically has **owner** access.


```json
{
  "created_by": "usr_abc123"  // This user is always owner
}
```

### 2. Edit Access

Users have **edit** access if they match any of:

- Their user ID is in `editable_by_users` array
- Their role ID is in `editable_by_roles` array



```json
{
  "editable_by_users": ["usr_def456", "usr_ghi789"],
  "editable_by_roles": ["role_admin", "role_manager"]
}
```

### 3. View Access

Users have **view** access if they match any of:

- `access_mode` is set to `"public"` (everyone can view)
- `access_mode` is set to `"organization"` (all organization members can view)
- Their user ID is in `access_users` array
- Their department ID is in `access_departments` array
- Their role ID is in `visible_to_roles` array
- Their user ID is in `visible_in_chat_to_users` array (chat visibility only)



```json
{
  "access_mode": "private",
  "access_users": ["usr_jkl012"],
  "access_departments": ["dept_engineering", "dept_sales"],
  "visible_to_roles": ["role_viewer"],
  "visible_in_chat_to_users": ["usr_mno345"]
}
```

### 4. No Access

If none of the above conditions match, the user has **no access** to the assistant.

## Access Control Fields

### `access_mode`

Controls the base visibility of the assistant.

**Values:**

- `"private"` - Only explicitly granted users can access (default)
- `"organization"` - All organization members can view
- `"public"` - Everyone in the organization can view



```json
{
  "access_mode": "organization"
}
```

### `access_departments`

Array of department IDs that have view access.


```json
{
  "access_departments": ["dept_engineering", "dept_product"]
}
```

### `access_users`

Array of user IDs that have view access.


```json
{
  "access_users": ["usr_abc123", "usr_def456"]
}
```

### `editable_by_users`

Array of user IDs that have edit access.


```json
{
  "editable_by_users": ["usr_ghi789"]
}
```

### `editable_by_roles`

Array of role IDs that have edit access.


```json
{
  "editable_by_roles": ["role_admin", "role_manager"]
}
```

### `visible_to_roles`

Array of role IDs that have view access.


```json
{
  "visible_to_roles": ["role_viewer", "role_analyst"]
}
```

### `visible_in_chat_to_users`

Array of user IDs that can see the assistant in chat (view-only).


```json
{
  "visible_in_chat_to_users": ["usr_jkl012"]
}
```

## Common Access Patterns

### Private Assistant (Creator Only)

Only the creator can access the assistant.


```json
{
  "name": "My Private Assistant",
  "organization_id": "org_abc123",
  "access_mode": "private"
}
```

### Organization-Wide Assistant

All organization members can view, specific users can edit.


```json
{
  "name": "Company Assistant",
  "organization_id": "org_abc123",
  "access_mode": "organization",
  "editable_by_roles": ["role_admin"]
}
```

### Department-Specific Assistant

Only engineering and product departments can view.


```json
{
  "name": "Engineering Assistant",
  "organization_id": "org_abc123",
  "access_mode": "private",
  "access_departments": ["dept_engineering", "dept_product"],
  "editable_by_users": ["usr_lead_engineer"]
}
```

### Role-Based Assistant

Specific roles can view, admins can edit.


```json
{
  "name": "Manager Assistant",
  "organization_id": "org_abc123",
  "access_mode": "private",
  "visible_to_roles": ["role_manager", "role_director"],
  "editable_by_roles": ["role_admin"]
}
```

### Team Collaboration Assistant

Multiple users can edit, broader team can view.


```json
{
  "name": "Team Assistant",
  "organization_id": "org_abc123",
  "access_mode": "private",
  "access_users": ["usr_member1", "usr_member2", "usr_member3"],
  "editable_by_users": ["usr_lead1", "usr_lead2"]
}
```

## API Behavior

### Create Assistant

When creating an assistant, the creator automatically receives **owner** access.


```bash
curl https://api.aitronos.com/v1/assistants \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Assistant",
    "organization_id": "org_abc123",
    "access_mode": "organization",
    "editable_by_roles": ["role_admin"]
  }'
```

**Response includes `user_access_level`:**


```json
{
  "id": "asst_abc123",
  "name": "My Assistant",
  "user_access_level": "owner",
  ...
}
```

### List Assistants

Only returns assistants the user has access to (view, edit, or owner).


```bash
curl "https://api.aitronos.com/v1/assistants?organization_id=org_abc123" \
  -H "X-API-Key: $FREDDY_API_KEY"
```

**Response:**


```json
{
  "assistants": [
    {
      "id": "asst_abc123",
      "name": "My Assistant",
      "user_access_level": "owner"
    },
    {
      "id": "asst_def456",
      "name": "Team Assistant",
      "user_access_level": "edit"
    },
    {
      "id": "asst_ghi789",
      "name": "Company Assistant",
      "user_access_level": "view"
    }
  ]
}
```

### Get Assistant

Requires at least **view** access.


```bash
curl https://api.aitronos.com/v1/assistants/asst_abc123 \
  -H "X-API-Key: $FREDDY_API_KEY"
```

**403 Forbidden if no access:**


```json
{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "You don't have permission to access this assistant",
    "status": 403,
    "details": {
      "assistant_id": "asst_abc123",
      "required_level": "view",
      "user_level": "none"
    }
  }
}
```

### Update Assistant

Requires **edit** or **owner** access.


```bash
curl -X PUT https://api.aitronos.com/v1/assistants/asst_abc123 \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Assistant Name"
  }'
```

**403 Forbidden if only view access:**


```json
{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "You don't have permission to access this assistant",
    "status": 403,
    "details": {
      "assistant_id": "asst_abc123",
      "required_level": "edit",
      "user_level": "view"
    }
  }
}
```

### Delete Assistant

Requires **owner** access only.


```bash
curl -X DELETE https://api.aitronos.com/v1/assistants/asst_abc123 \
  -H "X-API-Key: $FREDDY_API_KEY"
```

**403 Forbidden if not owner:**


```json
{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "You don't have permission to access this assistant",
    "status": 403,
    "details": {
      "assistant_id": "asst_abc123",
      "required_level": "owner",
      "user_level": "edit"
    }
  }
}
```

## Updating Access Control

You can modify access control settings by updating the assistant:


```bash
curl -X PUT https://api.aitronos.com/v1/assistants/asst_abc123 \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "access_mode": "organization",
    "editable_by_users": ["usr_new_editor"],
    "visible_to_roles": ["role_viewer"]
  }'
```

## Best Practices

### Start Private, Expand Gradually

Create assistants as private and grant access incrementally:


```json
{
  "access_mode": "private",
  "access_users": ["usr_teammate1"]
}
```

### Use Roles for Scalability

Instead of managing individual users, use roles:


```json
{
  "visible_to_roles": ["role_engineering"],
  "editable_by_roles": ["role_engineering_lead"]
}
```

### Combine Access Methods

Layer multiple access controls for flexibility:


```json
{
  "access_mode": "private",
  "access_departments": ["dept_engineering"],
  "access_users": ["usr_external_consultant"],
  "editable_by_roles": ["role_admin"]
}
```

### Organization-Wide with Edit Restrictions

Make assistants visible to everyone but editable by few:


```json
{
  "access_mode": "organization",
  "editable_by_users": ["usr_owner", "usr_maintainer"]
}
```

## Access Level Summary

| Action | Owner | Edit | View | None |
|  --- | --- | --- | --- | --- |
| View assistant details | ✅ | ✅ | ✅ | ❌ |
| Update configuration | ✅ | ✅ | ❌ | ❌ |
| Update access control | ✅ | ✅ | ❌ | ❌ |
| Delete assistant | ✅ | ❌ | ❌ | ❌ |
| Use in conversations | ✅ | ✅ | ✅ | ❌ |
| View in list | ✅ | ✅ | ✅ | ❌ |


## Related Resources

- [Create Assistant](/docs/api-reference/assistants/create) - Create a new assistant with access control
- [Update Assistant](/docs/api-reference/assistants/update) - Modify assistant access settings
- [List Assistants](/docs/api-reference/assistants/list) - View accessible assistants
- [Assistant Object](/docs/api-reference/objects/assistant-object) - Complete field reference