Skip to main content

User Permission Levels

Overview​

CROW implements a permission-based access control system that allows fine-grained control over what users and API keys can access. This is critical for a data platform where different team members may need different levels of access to sensitive interaction and pattern data.

Permission Model​

CROW uses a toggle-based permission system rather than traditional role-based access control (RBAC). This provides flexibility for organizations to create custom access patterns for their team members.

API Key Permissions​

API keys have simple on/off toggles for data access:

Interactions Permission​

  • On: API key can access interaction data
  • Off: API key cannot access interaction data

Patterns Permission​

  • On: API key can access pattern data
  • Off: API key cannot access pattern data

Use Cases:

  • External integrations that only need read access to specific data types
  • Developer testing with limited scope
  • Third-party analytics tools with restricted access
  • Audit and compliance requirements

User Permissions​

User permissions are more granular, with specific controls for different features.

Chat Access​

Chat access has constraint-based permissions:

Duration Constraint​

  • Minimum: 1 year of data
  • Configuration: Admin can set minimum duration (e.g., 1yr, 6mo, 3mo)
  • Purpose: Limit historical data access for users

Component Constraint​

  • Minimum: 1 component access required
  • Options: Web, Social, CCTV
  • Configuration: Admin selects which components user can query
  • Purpose: Restrict data source access based on role

Example Configurations:

  • Sales team: Web + Social components, 6 months duration
  • Executive: All components, all-time duration
  • Support team: Web component only, 3 months duration

Feature Access Toggles​

All other features use simple on/off toggles:

  • Interactions: Can view raw interaction data
  • Patterns: Can view pattern data
  • Teams: Can manage team members and invitations
  • API Keys: Can create and manage API keys
  • Billing: Can view billing and analytics
  • Settings: Can access organization settings
  • Notifications: Can view notifications (typically always on)
  • Integrations: Can configure component integrations
  • Product Management: Can manage product catalog

Permission Management​

Setting Permissions​

Organization admins and users with Teams permission can:

  1. Invite new team members
  2. Set initial permissions during invitation
  3. Modify permissions for existing users
  4. Remove team members

Permission Inheritance​

  • Organization Owner: Has all permissions by default
  • New Users: Receive default permission set (configurable)
  • Invited Users: Receive permissions specified in invitation

Permission Validation​

Permissions are validated at multiple levels:

  1. Frontend: UI elements hidden based on permissions
  2. API Gateway: Request authorization before routing
  3. Service Level: Each service validates permissions
  4. JWT Claims: Permissions encoded in JWT for efficient validation

Default Permission Sets​

Owner​

  • All permissions enabled
  • Cannot be modified
  • One owner per organization

Admin​

  • All feature access
  • Can manage team members
  • Can manage API keys
  • Can configure billing

Member (Default)​

  • Chat access (all components, 1 year duration)
  • View interactions
  • View patterns
  • View notifications
  • No administrative access

Developer​

  • Chat access (all components, 6 months)
  • View interactions
  • Manage API keys
  • Access integrations

Analyst​

  • Chat access (all components, all-time)
  • View interactions
  • View patterns
  • View billing analytics

Best Practices​

Principle of Least Privilege​

  • Grant only necessary permissions
  • Review permissions regularly
  • Remove unused permissions
  • Audit permission changes

Permission Auditing​

  • All permission changes are logged
  • Review logs for compliance
  • Monitor unusual access patterns
  • Track permission escalation

API Key Management​

  • Create separate keys for different integrations
  • Use minimal permissions per key
  • Rotate keys regularly
  • Revoke unused keys immediately

Technical Implementation​

Permission Storage​

Permissions are stored in the User Service database:

CREATE TABLE user_permissions (
    user_id TEXT PRIMARY KEY REFERENCES users(id),
    
    -- Chat constraints
    chat_enabled BOOLEAN DEFAULT true,
    chat_min_duration TEXT DEFAULT '1yr',
    chat_components JSON DEFAULT '["web"]',
    
    -- Feature toggles
    interactions_enabled BOOLEAN DEFAULT true,
    patterns_enabled BOOLEAN DEFAULT true,
    teams_enabled BOOLEAN DEFAULT false,
    api_keys_enabled BOOLEAN DEFAULT false,
    billing_enabled BOOLEAN DEFAULT false,
    settings_enabled BOOLEAN DEFAULT false,
    notifications_enabled BOOLEAN DEFAULT true,
    integrations_enabled BOOLEAN DEFAULT false,
    products_enabled BOOLEAN DEFAULT false,
    
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

JWT Claims​

Permissions are included in JWT tokens for efficient validation:

{
  "sub": "user_id",
  "org": "org_id",
  "permissions": {
    "chat": {
      "enabled": true,
      "duration": "1yr",
      "components": ["web", "social"]
    },
    "interactions": true,
    "patterns": true,
    "teams": false,
    "apiKeys": false
  }
}

Frontend Permission Checks​

// Example permission check in frontend
if (user.permissions.teams) {
  // Show team management UI
}

if (user.permissions.chat?.components.includes('cctv')) {
  // Enable CCTV data queries in chat
}

Future Enhancements​

Planned Features​

  • Custom permission roles (beyond default sets)
  • Time-based permission grants (temporary access)
  • IP-based restrictions for sensitive operations
  • Two-factor authentication for permission changes
  • Automated permission reviews and alerts

Under Consideration​

  • Row-level security (RLS) for data access
  • Field-level permissions (e.g., hide PII)
  • External identity provider integration
  • Permission templates for common scenarios