# Organization Management Overview

div
strong
🔨 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](/docs/api-reference/objects/organization-object) 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.

## Related Objects

- [Organization](/docs/api-reference/objects/organization-object)
- [OrganizationUser](/docs/api-reference/objects/organization-user-object)
- [Role](/docs/api-reference/objects/role-object)
- [UserStatus](/docs/api-reference/objects/user-status-object)
- [UserInvitation](/docs/api-reference/objects/user-invitation-object)
- [Department](/docs/api-reference/objects/department-object)
- [UserDepartment](/docs/api-reference/objects/user-department-object)
- [OrganizationDomain](/docs/api-reference/objects/organization-domain-object)
- [OrganizationProvider](/docs/api-reference/objects/organization-provider-object)