Assistant Access Management
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude

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.

{
  "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

{
  "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)

{
  "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

{
  "access_mode": "organization"
}

`access_departments`

Array of department IDs that have view access.

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

`access_users`

Array of user IDs that have view access.

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

`editable_by_users`

Array of user IDs that have edit access.

{
  "editable_by_users": ["usr_ghi789"]
}

`editable_by_roles`

Array of role IDs that have edit access.

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

`visible_to_roles`

Array of role IDs that have view access.

{
  "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).

{
  "visible_in_chat_to_users": ["usr_jkl012"]
}

Common Access Patterns

Private Assistant (Creator Only)

Only the creator can access the assistant.

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

Organization-Wide Assistant

All organization members can view, specific users can edit.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

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:

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

List Assistants

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

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

Response:

{
  "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.

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

403 Forbidden if no access:

{
  "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.

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:

{
  "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.

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

403 Forbidden if not owner:

{
  "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:

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:

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

Use Roles for Scalability

Instead of managing individual users, use roles:

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

Combine Access Methods

Layer multiple access controls for flexibility:

{
  "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:

{
  "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	✅	✅	✅	❌

Create Assistant - Create a new assistant with access control
Update Assistant - Modify assistant access settings
List Assistants - View accessible assistants
Assistant Object - Complete field reference

Assistant Access ManagementCopyCopy for LLMCopy page as Markdown for LLMsView as MarkdownOpen this page as MarkdownOpen in ChatGPTGet insights from ChatGPTOpen in ClaudeGet insights from Claude