Organization Settings

Organization Settings

This guide covers organization-level configuration, team management, and organization-wide defaults in Querri.

Overview

Organization settings control system-wide behavior, defaults, and policies that apply to all users within your Querri deployment.

Accessing Organization Settings

Organization settings are available through the Settings menu:

https://app.yourcompany.com/settings

Available Settings Pages:

• /settings - General account settings
• /settings/people - User management
• /settings/appearance - UI customization
• /settings/customize - Branding and white-label
• /settings/integrations - Integration marketplace (admin only)
• /settings/usage - Usage metrics and quotas
• /settings/subscription - Billing and subscription

Organization Structure

Organization Model

Each Querri deployment can support multiple organizations:

{
  _id: "org_xxxxxxxxxxxxx",
  name: "Your Company Name",
  created_at: "2024-01-15T10:00:00Z",
  settings: {
    default_role: "member",
    allow_public_sharing: true,
    require_2fa: false,
    max_storage_gb: 1000
  },
  members: [
    {
      email: "user@company.com",
      role: "admin",
      joined_at: "2024-01-15T10:00:00Z"
    }
  ],
  branding: {
    logo_url: "https://...",
    primary_color: "#1e40af",
    custom_domain: "analytics.company.com"
  }
}

Viewing Organization Details

View organization information via MongoDB:

# Connect to MongoDB
docker compose exec mongo mongosh -u querri -p

# View organization
use querri
db.organizations.findOne({name: "Your Company Name"})

General Configuration

Organization Name

Update organization name:

db.organizations.updateOne(
  {_id: "org_xxxxxxxxxxxxx"},
  {$set: {name: "New Company Name"}}
)

Note: Organization name appears in:

• Email communications
• Share links
• User interface headers

Organization ID

The organization ID (linked to WorkOS) identifies your organization:

# Find organization ID
db.organizations.findOne({}, {_id: 1, name: 1})

This ID is used in:

• WorkOS configuration (WORKOS_PUBLIC_ORG)
• API requests
• Permission checks

Team Settings

Default User Role

Set the default role for new users:

db.organizations.updateOne(
  {_id: "org_xxxxxxxxxxxxx"},
  {$set: {"settings.default_role": "member"}}
)

Options:

• guest - Read-only access
• member - Standard user (default)
• admin - Full administrative access

Recommendation: Use member as default, manually promote to admin as needed.

Member Management

Adding Members

Add members to organization:

db.organizations.updateOne(
  {_id: "org_xxxxxxxxxxxxx"},
  {
    $push: {
      members: {
        email: "newuser@company.com",
        role: "member",
        joined_at: new Date()
      }
    }
  }
)

Removing Members

Remove members from organization:

db.organizations.updateOne(
  {_id: "org_xxxxxxxxxxxxx"},
  {
    $pull: {
      members: {email: "user@company.com"}
    }
  }
)

Updating Member Roles

Change a member’s role:

db.organizations.updateOne(
  {
    _id: "org_xxxxxxxxxxxxx",
    "members.email": "user@company.com"
  },
  {
    $set: {"members.$.role": "admin"}
  }
)

Default Permissions

Project Permissions

Configure default permissions for new projects:

db.organizations.updateOne(
  {_id: "org_xxxxxxxxxxxxx"},
  {
    $set: {
      "settings.default_project_permissions": {
        allow_sharing: true,
        default_visibility: "private",
        allow_public_links: true
      }
    }
  }
)

Settings:

• allow_sharing: Users can share projects with others
• default_visibility: private or organization
• allow_public_links: Enable public share links

Organization-Wide Access

Grant all members access to certain resources:

db.organizations.updateOne(
  {_id: "org_xxxxxxxxxxxxx"},
  {
    $set: {
      "settings.organization_wide_access": {
        projects: false,  // All users see all projects
        dashboards: true, // All users see all dashboards
        files: false      // Files remain private
      }
    }
  }
)

Resource Limits

Storage Quotas

Set organization-wide storage limits:

db.organizations.updateOne(
  {_id: "org_xxxxxxxxxxxxx"},
  {
    $set: {
      "settings.limits": {
        max_storage_gb: 1000,
        max_projects: -1,      // -1 = unlimited
        max_users: 100,
        max_api_calls_per_day: 100000
      }
    }
  }
)

Per-User Limits

Set per-user resource limits:

db.organizations.updateOne(
  {_id: "org_xxxxxxxxxxxxx"},
  {
    $set: {
      "settings.per_user_limits": {
        max_projects: 50,
        max_storage_gb: 10,
        max_dashboard_widgets: 20
      }
    }
  }
)

Rate Limiting

Configure API rate limits:

db.organizations.updateOne(
  {_id: "org_xxxxxxxxxxxxx"},
  {
    $set: {
      "settings.rate_limits": {
        api_calls_per_minute: 100,
        file_uploads_per_hour: 50,
        ai_requests_per_day: 1000
      }
    }
  }
)

Checking Current Usage

View organization resource usage:

// Total projects
db.projects.find({organization_id: "org_xxxxxxxxxxxxx"}).count()

// Total users
db.organizations.findOne(
  {_id: "org_xxxxxxxxxxxxx"},
  {members: 1}
).members.length

// Storage usage (files collection)
db.files.aggregate([
  {$match: {organization_id: "org_xxxxxxxxxxxxx"}},
  {$group: {_id: null, total_bytes: {$sum: "$size"}}}
])

Branding Basics

Organization-level branding settings (see White Label Configuration for details):

Organization Logo

db.organizations.updateOne(
  {_id: "org_xxxxxxxxxxxxx"},
  {
    $set: {
      "branding.logo_url": "https://yourcompany.com/logo.png"
    }
  }
)

Primary Color

db.organizations.updateOne(
  {_id: "org_xxxxxxxxxxxxx"},
  {
    $set: {
      "branding.primary_color": "#1e40af"
    }
  }
)

Company Information

db.organizations.updateOne(
  {_id: "org_xxxxxxxxxxxxx"},
  {
    $set: {
      "branding.company_name": "Your Company",
      "branding.support_email": "support@yourcompany.com",
      "branding.website": "https://yourcompany.com"
    }
  }
)

Feature Toggles

Enable or disable features organization-wide:

db.organizations.updateOne(
  {_id: "org_xxxxxxxxxxxxx"},
  {
    $set: {
      "settings.features": {
        ai_assistant: true,
        dashboards: true,
        integrations: true,
        public_sharing: true,
        api_access: true,
        scheduled_jobs: true,
        data_export: true
      }
    }
  }
)

Feature Descriptions

• ai_assistant: Enable AI-powered analysis and chat
• dashboards: Allow users to create dashboards
• integrations: Enable integration marketplace
• public_sharing: Allow public share links
• api_access: Enable API access for users
• scheduled_jobs: Allow scheduled/automated tasks
• data_export: Enable data export features

Security Settings

Two-Factor Authentication

Require 2FA for organization members:

db.organizations.updateOne(
  {_id: "org_xxxxxxxxxxxxx"},
  {
    $set: {
      "settings.security": {
        require_2fa: true,
        session_timeout_minutes: 480,  // 8 hours
        password_expiry_days: 90,
        allowed_ip_ranges: []  // Empty = all IPs allowed
      }
    }
  }
)

IP Whitelisting

Restrict access to specific IP ranges:

db.organizations.updateOne(
  {_id: "org_xxxxxxxxxxxxx"},
  {
    $set: {
      "settings.security.allowed_ip_ranges": [
        "203.0.113.0/24",
        "198.51.100.0/24"
      ]
    }
  }
)

Session Configuration

Configure session behavior:

db.organizations.updateOne(
  {_id: "org_xxxxxxxxxxxxx"},
  {
    $set: {
      "settings.security.session_timeout_minutes": 480,
      "settings.security.require_reauthentication_for_sensitive_actions": true
    }
  }
)

Data Retention

Configure data retention policies:

db.organizations.updateOne(
  {_id: "org_xxxxxxxxxxxxx"},
  {
    $set: {
      "settings.retention": {
        project_history_days: 365,
        deleted_items_retention_days: 30,
        log_retention_days: 90,
        export_data_retention_days: 7
      }
    }
  }
)

Integration Settings

Organization-Wide Integrations

Some integrations can be deployed organization-wide (admin only):

db.organizations.updateOne(
  {_id: "org_xxxxxxxxxxxxx"},
  {
    $set: {
      "settings.integrations": {
        prismatic_enabled: true,
        default_integrations: [
          "salesforce",
          "slack",
          "google-sheets"
        ]
      }
    }
  }
)

API Keys

Organization-level API keys for external services:

db.organizations.updateOne(
  {_id: "org_xxxxxxxxxxxxx"},
  {
    $set: {
      "settings.api_keys": {
        // Encrypted API keys for org-wide integrations
        salesforce: "encrypted_key_here",
        slack: "encrypted_key_here"
      }
    }
  }
)

Notification Settings

Configure organization-wide notification preferences:

db.organizations.updateOne(
  {_id: "org_xxxxxxxxxxxxx"},
  {
    $set: {
      "settings.notifications": {
        email_notifications: true,
        digest_frequency: "daily",  // daily, weekly, never
        notify_on_sharing: true,
        notify_on_comments: true,
        notify_on_job_completion: true
      }
    }
  }
)

Usage Quotas

Monitor and enforce usage quotas:

Setting Quotas

db.organizations.updateOne(
  {_id: "org_xxxxxxxxxxxxx"},
  {
    $set: {
      "settings.quotas": {
        ai_tokens_per_month: 1000000,
        api_calls_per_month: 500000,
        storage_gb: 1000,
        users: 100
      }
    }
  }
)

Checking Quota Usage

// View current quotas and usage
db.organizations.findOne(
  {_id: "org_xxxxxxxxxxxxx"},
  {
    "settings.quotas": 1,
    "usage_stats": 1
  }
)

Organization Metadata

Custom Fields

Add custom metadata to organization:

db.organizations.updateOne(
  {_id: "org_xxxxxxxxxxxxx"},
  {
    $set: {
      metadata: {
        industry: "Healthcare",
        employee_count: "1000-5000",
        deployment_region: "us-east-1",
        contract_start: "2024-01-01",
        contract_end: "2025-01-01",
        custom_field_1: "value"
      }
    }
  }
)

Tags and Categories

Organize organizations with tags:

db.organizations.updateOne(
  {_id: "org_xxxxxxxxxxxxx"},
  {
    $set: {
      tags: ["enterprise", "healthcare", "tier-1"]
    }
  }
)

Multi-Organization Management

For deployments with multiple organizations:

Listing All Organizations

// List all organizations
db.organizations.find(
  {},
  {name: 1, created_at: 1, "members": {$size: "$members"}}
).sort({created_at: -1})

Organization Templates

Create a template for new organizations:

// Template organization settings
const orgTemplate = {
  settings: {
    default_role: "member",
    features: {
      ai_assistant: true,
      dashboards: true,
      integrations: true
    },
    limits: {
      max_storage_gb: 100,
      max_users: 50
    }
  }
}

// Apply template to new organization
db.organizations.insertOne({
  name: "New Company",
  created_at: new Date(),
  ...orgTemplate
})

Migrating Organization Settings

Export Organization Settings

# Export organization configuration
docker compose exec mongo mongosh -u querri -p --eval '
  db.getSiblingDB("querri").organizations.findOne(
    {_id: "org_xxxxxxxxxxxxx"}
  )
' > org_settings_backup.json

Import Organization Settings

# Import organization configuration
docker compose exec -T mongo mongosh -u querri -p querri < org_settings_backup.json

Default Configurations

Recommended Production Settings

{
  settings: {
    default_role: "member",
    features: {
      ai_assistant: true,
      dashboards: true,
      integrations: true,
      public_sharing: true,
      api_access: true,
      scheduled_jobs: true,
      data_export: true
    },
    limits: {
      max_storage_gb: 1000,
      max_users: 100,
      max_projects: -1  // unlimited
    },
    security: {
      require_2fa: true,
      session_timeout_minutes: 480,
      allowed_ip_ranges: []
    },
    retention: {
      project_history_days: 365,
      deleted_items_retention_days: 30,
      log_retention_days: 90
    },
    notifications: {
      email_notifications: true,
      digest_frequency: "daily"
    }
  }
}

Minimal Configuration

{
  settings: {
    default_role: "member",
    features: {
      ai_assistant: true,
      dashboards: true
    },
    limits: {
      max_storage_gb: 100,
      max_users: 50
    }
  }
}

Troubleshooting

Organization Not Found

// List all organizations
db.organizations.find({}, {name: 1, _id: 1})

// Search by name
db.organizations.findOne({name: /company/i})

Settings Not Applying

1. Verify organization ID matches WorkOS configuration
2. Check settings syntax is correct
3. Restart services after changes:

   docker compose restart web-app server-api hub

Member Issues

// Verify member exists in organization
db.organizations.findOne(
  {members: {$elemMatch: {email: "user@company.com"}}},
  {name: 1, "members.$": 1}
)

Best Practices

1. Review settings quarterly - Ensure limits and features match current needs
2. Document changes - Keep changelog of organization setting changes
3. Test in development - Verify setting changes before applying to production
4. Monitor quotas - Set up alerts for quota usage (80%, 90%, 100%)
5. Regular backups - Export organization settings before major changes
6. Principle of least privilege - Start restrictive, expand as needed

Next Steps

• User Management - Manage organization members
• White Label Configuration - Customize organization branding
• Security & Permissions - Configure security policies
• Monitoring & Usage - Track organization usage