Skip to content
Last updated

Access Management

🔨 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:

ModeDescriptionWho Can Access
privateOnly creatorCreator only
restrictedSpecific usersUsers in accessUsers list
departmentDepartment membersUsers in departments listed in accessDepartments
organizationAll org membersEveryone in the organization
globalCross-organizationUsers across multiple organizations
publicAnyoneAnyone with the link

Access Departments

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

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

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

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

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

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

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

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

Pattern 2: Department-Specific with Manager Editing

Department members can use it, managers can edit:

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

Pattern 3: Private with Specific Collaborators

Only creator and specific users can access and edit:

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

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

Pattern 5: Complex Multi-Level Access

Combine legacy and granular systems for maximum flexibility:

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

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

// ✅ 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

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

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"]
  }'
Previous page
Next page