Skip to content
Last updated

Organization Management Overview

🔨 In Development — This section is still being developed and may change.
Freddy's organization management system provides a comprehensive multi-tenant architecture for managing workspaces, teams, and access control.

Core Concepts

Organizations

Organizations are the primary container for all resources in Freddy. Each organization represents a company, team, or workspace with its own:

  • Members and access control
  • AI provider integrations
  • Resource limits and billing
  • Custom configurations

Multi-Organization Support

Users can belong to multiple organizations simultaneously, with different roles and permissions in each. Users can switch between organizations without re-authenticating.

Entity Relationships

Organization
├── OrganizationUser (membership)
│   ├── User
│   ├── Role (permissions)
│   └── UserStatus (state)
├── Department (team structure)
│   └── UserDepartment (assignments)
├── OrganizationDomain (auto-assignment)
├── OrganizationProvider (AI integrations)
└── UserInvitation (pending members)

Role-Based Access Control

Role Hierarchy

Owner

  • Complete control over organization
  • Manage billing and payments
  • Delete organization
  • Manage all users and settings

Admin

  • Manage users and members
  • Configure organization settings
  • Access all resources
  • Cannot manage billing

Member

  • Read-only access to organization
  • Use AI services
  • View resources
  • Cannot modify settings

Custom Roles

Organizations can create custom roles with tailored permission sets beyond the base roles.

User Status Lifecycle

InvitationSent → Active → Inactive → Deleted

Status States

InvitationSent: User invited but hasn't accepted Active: Full access to organization Inactive: Temporarily disabled Deleted: Removed from organization (soft delete)

Invitation Flow

  1. Admin invites user: Creates UserInvitation with unique key
  2. Email sent: User receives invitation link
  3. User accepts: Completes registration or logs in
  4. Status updated: UserStatus changes from InvitationSent to Active
  5. Access granted: User can access organization resources

Invitations expire after 7 days and can only be used once.

Domain-Based Auto-Assignment

Organizations can register email domains (e.g., aitronos.com) for automatic member assignment:

  1. User registers with matching email domain
  2. System finds OrganizationDomain record
  3. User automatically added to organization
  4. Assigned "Member" role by default
  5. Status set to "Active"

This enables seamless onboarding for company employees.

Department Structure

Departments provide team-based organization within companies:

Default Departments

  • Engineering
  • Sales
  • Marketing
  • Support
  • Operations

Features

  • Users can belong to multiple departments
  • Department-specific roles (member, lead, manager)
  • Color coding for visual identification
  • Custom departments can be created

Provider Integrations

Organizations can integrate multiple AI providers:

OpenAI: GPT models Anthropic: Claude models Freddy: Native models

Each provider has separate credentials and configuration, allowing organizations to use multiple providers simultaneously.

Resource Limits

Organizations have configurable limits:

API Usage Limit: Maximum API spending (CHF) Total Usage Limit: Overall spending cap (CHF) Storage Allowance: Free storage quota (bytes)

Limits can be customized per organization based on pricing tier.

Security Features

Soft Deletion

  • Users marked as deleted remain in database
  • Audit trail preserved
  • Can be restored if needed

Encrypted Credentials

  • Provider API keys encrypted at rest
  • Never exposed in API responses
  • Secure key rotation supported

Audit Logging

  • All membership changes tracked
  • Role modifications logged
  • Invitation usage recorded

Best Practices

Organization Setup

  1. Create organization with descriptive name
  2. Configure provider integrations
  3. Set up email domains for auto-assignment
  4. Create custom departments if needed
  5. Invite initial team members

Member Management

  1. Use invitations for new members
  2. Assign appropriate roles
  3. Organize users into departments
  4. Monitor invitation expiration
  5. Review member status regularly

Access Control

  1. Follow principle of least privilege
  2. Use custom roles for specific needs
  3. Regularly audit member permissions
  4. Remove inactive members
  5. Monitor role assignments

API Integration

All organization management operations are available via REST API:

  • Create and manage organizations
  • Invite and manage members
  • Configure roles and permissions
  • Set up provider integrations
  • Manage departments and assignments

See individual endpoint documentation for details.

Previous page
Next page