Mesibo Backend APIs - User Access Control (UAC)

UAC allows you to assign different feature sets to different classes of users instead of managing each user and each feature individually. UAC provides granular controls across messaging, calls, presence, group calls, location, files, and more, enabling you to configure and assign precise capabilities to different user segments in your app. User segments vary by application type, for example:

• Social Apps: Free users vs. paid subscribers
• Telemedicine: Doctors, patients, administrative staff
• Enterprise: HR, managers, employees, contractors
• Education: Teachers, students, administrators
• Marketplaces: Buyers, sellers, verified merchants

Each segment can be assigned different UAC configurations with specific feature sets tailored to their needs and subscription level. When you need to change feature sets or enhance your app with new capabilities, simply modify the UAC configuration once and it automatically applies to all assigned users, eliminating the need to update each user individually. Similarly, you can instantly change a user's feature set by switching their assigned UAC. For example, when a free user becomes a paid subscriber, assigning them a different UAC immediately grants them the enhanced feature set without any manual configuration.

For example, one of the mesibo powered social apps required online status and read receipts to be available only to paid subscribers. The app created two UAC configurations: one for free users with these features disabled, and another for premium users with all features enabled. When a user upgrades to a premium subscription, the app simply assigns them the premium UAC and they instantly gain access to online status and read receipts. If their subscription lapses, switching them back to the free UAC immediately revokes those premium features. This approach scales effortlessly whether managing hundreds or millions of users. UAC changes take effect instantly across all assigned users.

UAC Features and Benefits

• Centralized Management: Define feature sets once and apply to multiple users.
• Easy Updates: Modify a UAC configuration to instantly update all users assigned to it
• Scalability: As new features are added, simply update UAC configurations instead of modifying millions of users individually.
• Device-Specific Configurations: Configure different features for different platforms. For example, some mesibo customers provide limited features to web-based apps compared to mobile apps. UAC allows you to configure features per device type.
• Time-Limited Features: UAC can be applied for a limited duration, allowing you to provide time-limited demos or subscription features that expire automatically. For example, users can access premium features while their subscription is valid, during a specific event, or for an app trial period.
• Geographical Feature Control: Based on geographical proximity or user location, you can configure different media upload limits, assign specific TURN servers, or enable and disable feature sets.
• Multi-Device Support: Apply different UAC configurations in multi-device login scenarios. For example, enable a primary device to make and receive calls while a secondary device can only receive calls.

Any change in UAC or assignment is real-time and applies instantly. When you assign a UAC configuration to a user, they are instantly reconnected with the new configuration. When you modify a UAC configuration, all assigned users receive the updated settings on their next communication event or login.

Minimum Requirements

API Version

• Android, iOS, Python, C++: v2.9.0 or higher
• JavaScript: v2.6.0 or higher

While earlier versions may support partial UAC features (some UAC capabilities were provided to specific customers as early releases), they are not officially supported. For full UAC functionality and support, ensure you are using the minimum required versions listed above.

On-Premise Deployment

• Minimum build: 9900

If you are running mesibo on-premise, you must be on build 9900 or higher to use above API versions.

Migration from user.permissions

Important: The user.permissions parameter in the User Management API will be deprecated by June 1st, 2026 for existing applications. Please migrate to UAC before this date.

For new applications: UAC is the only way to configure user features. The user.permissions parameter will not apply to new applications.

For existing applications: You have until June 1st, 2026 to migrate from user.permissions to UAC. After this date, user.permissions will no longer be functional.

Migration path:

1. Create UAC configurations that match your current permission sets
2. Assign appropriate UAC IDs to your users
3. Test thoroughly before the deprecation date
4. Remove user.permissions from your user management backend API calls

UAC Configuration

Each UAC configuration is identified by a numerical ID from 1 to 64.

For each UAC ID, you can create separate configurations for different device types (Android, iOS, JavaScript/Web, Python, C++, SFU) as well as a default configuration that applies when no device-specific configuration exists. This allows creating up to 64 × 6 = 384 different UAC configurations, meeting virtually any deployment requirement.

Once created, UAC configurations can be assigned to users during user creation (useradd) or later using user modification (userset) operations by specifying the UAC ID.

Default UAC Configuration (ID: 1)

UAC ID 1 serves as the default UAC configuration for your application. When you create a UAC configuration with ID 1, it automatically applies to all users who are not explicitly assigned a specific UAC ID. This is useful for setting baseline features and limits across your entire user base.

You can override the default configuration for specific users by assigning them a different UAC ID.

UAC Application Order

When a user connects, mesibo applies UAC settings in the following priority order based on the device from which the user has logged in:

1. User's assigned UAC: If a UAC ID is assigned to the user:

   • First, check if a device-specific configuration exists for that UAC ID
   • Else, check if a default (device-agnostic) configuration exists for that UAC ID

2. Else, Parent user's UAC: If the user has a parent user (multi-device login) with an assigned UAC ID:

   • First, check if a device-specific configuration exists for that UAC ID
   • Else, check if a default configuration exists for that UAC ID

3. Else, Application default UAC (ID 1): If UAC ID 1 exists:

   • First, check if a device-specific configuration exists
   • Else, use the default configuration for UAC ID 1

4. Else, No restrictions: If no UAC configuration matches, all features are enabled

Multi-Device Login Support

mesibo supports users logging in from multiple devices simultaneously. Refer to the Multi-Device Login and Synchronization documentation for details on how multi-device login works.

UAC can be applied to individual device logins, enabling special scenarios such as:

• Read-only devices: A tablet or TV device can have read-only access while the primary phone has full access
• Limited feature devices: A web login can have restricted calling features while mobile devices have full capabilities
• Guest devices: Temporary devices can have limited permissions

When you create a user token with a device or linkto parameter, mesibo creates a linked user with its own uid. You can assign different UAC IDs to:

• The parent user (applies to all devices by default)
• Individual linked users/devices (device-specific feature restrictions)

Important: In multi-device configurations, messages or calls are generally addressed to the parent user, and the parent's UAC configuration is applied first. Even if a linked device has a UAC with more permissive features, those additional features will not apply if they exceed the parent user's permissions. Therefore, it is important to configure linked device UAC as a subset of the parent user's UAC. The linked device UAC should only restrict features further, not expand them beyond what the parent user is allowed.

Creating or Modifying a UAC Configuration

To create a new UAC configuration or modify an existing one, send the following JSON request to the backend API:

{
  "op": "uacset",
  "token": "ptlk9hdel1gqxf3p0s15f5f5gtusldej18tl794suzit",
  "uac": {
    "id": 1,
    "name": "Default UAC",
    "peers": 0,
    
    "app": {
      "name": "My Application Feature",
      "data": "{\"custom\": \"config\"}"
    },
    
    "features": {
      "group": 1,
      "e2ee": 1,
      "message": 1,
      "presence": 1,
      "call": 1,
      "sync": 1,
      "location": 1
    },
    
    "message": {
      "incoming": 1,
      "outgoing": 1,
      "rich": 1,
      "broadcast": 0,
      "read_receipts": 1,
      "delivery_receipts": 1,
      "storage": 1,
      "url_preview": 1,
      "webhook": 0,
      "ratelimit": 100
    },
    
    "presence": {
      "typing": 1,
      "online": 1,
      "joined": 1,
      "lastseen": 1,
      "lastseen_resolution": 300
    },
    
    "call": {
      "incoming": 1,
      "outgoing": 1,
      "video": 1,
      "audio": 1,
      "turn": 1,
      "hd": 1,
      "fhd": 1,
      "maxdur": 3600,
      "turn_server": "turn.example.com:3478"
    },
    
    "conf": {
      "video": 1,
      "audio": 1,
      "screen": 1,
      "hd": 1,
      "fhd": 1,
      "maxdur": 7200
    },
    
    "group": {
      "create": 1,
      "message": 1,
      "presence": 1,
      "call": 1,
      "location": 1,
      "max_groups": 100
    },
    
    "file": {
      "keepalive": 60,
      "max_size": 50,
      "upload_url": "https://example.com/upload",
      "exts": ""
    },
    
    "location": {
      "emulator": 0,
      "mock": 0,
      "send_real": 1,
      "send_age": 300,
      "can_sub": 1,
      "anti_triang": 0,
      
      "user": {
        "reach": 5000,
        "accuracy": 100,
        "fuzziness": 0,
        "maxage": 3600
      },
      
      "group": {
        "reach": 10000,
        "maxage": 3600
      },
      
      "subs": {
        "count": 100,
        "duration": 86400,
      }
    },
    
    "proximity_search": {
      "user": {
        "min_radius": 100,
        "max_radius": 50000,
        "maxage": 3600,
        "reach": 50000,
        "bounds": 1
      },
      
      "group": {
        "min_radius": 100,
        "max_radius": 50000,
        "maxage": 3600,
        "reach": 50000,
        "bounds": 1
      }
    }
  }
}

Basic Parameters

Platform Parameters

UAC configurations can be created for specific device platforms, allowing you to provide different feature sets based on the device type. For each UAC ID, you can create separate configurations for different platforms as well as a default configuration that applies when no device-specific configuration exists.

Usage:

• Use either the platforms string parameter OR individual platform flags (android, ios, etc.)
• Empty/not specified platforms means the configuration applies to all platforms (default)
• When updating UAC, only a single platform or no platform can be specified

Examples:

// Default configuration for all platforms
{
  "uac": {
    "id": 1,
    "platforms": ""  // or omit platforms parameter
  }
}

// Android-only configuration
{
  "uac": {
    "id": 2,
    "android": 1
  }
}

// Web and mobile configuration using string
{
  "uac": {
    "id": 3,
    "platforms": "android,ios,javascript"
  }
}

App Data Parameters

Application-specific custom data:

Features Parameters

Master switches for major capabilities:

If group features are enabled, various group features such as group messaging, calling, etc. can be further controlled from the group object described below.

Message Parameters

Control messaging capabilities:

Presence Parameters

Control presence and activity indicators:

Note: The online_audience parameter provides privacy control over online status visibility. Client applications can use the setOnlineStatusAudience() API to change this setting if can_override is enabled.

Call Parameters

Control one-to-one voice and video calling:

Conference Parameters

Control group conferencing capabilities:

Group Parameters

Control group-related features at the user category/tier level. These parameters define what capabilities users of this UAC have in groups. Group administrators can further restrict these capabilities on a per-member basis using member permissions (see Group Management API), but cannot grant capabilities that the UAC doesn't allow.

Permission Hierarchy: Both UAC and group member permissions must allow a feature for it to work. The most restrictive permission wins.

Example Use Case - Tier-Based Restrictions:

// Free Tier Users (UAC 2)
"group": {
  "create": 1,
  "member": 1,
  "message": 1,
  "presence": 1,
  "call": 0,      // Free users cannot do group calls
  "location": 0,  // Free users cannot share location in groups
  "max_groups": 5
}

// Premium Tier Users (UAC 3)
"group": {
  "create": 1,
  "member": 1,
  "message": 1,
  "presence": 1,
  "call": 1,      // Premium users can do group calls
  "location": 1,  // Premium users can share location
  "max_groups": 100
}

In this example, even if a group administrator tries to enable call permissions for a free user in their group, the call will still be blocked because the user's UAC doesn't allow group.call. This ensures app-level tier restrictions cannot be bypassed by group admins.

Note: UAC group parameters act as capability gates. They define what features are available to users of this category. Group administrators can restrict these capabilities further for individual members within their groups, but cannot grant capabilities that the UAC blocks. This allows you to implement tier-based feature restrictions (e.g., free vs premium users) that group admins cannot override.

File Parameters

Control file upload and sharing:

Rate Limit Parameters

Rate limiting allows you to control how frequently users can perform specific actions (sending messages, making calls, uploading files, updating location, logging in) to prevent abuse and manage system resources.

How Rate Limiting Works

Rate limits are specified as time-window and limit pairs in the format: duration:limit,duration:limit,...

Format: duration1:limit1,duration2:limit2,duration3:limit3

• duration: Time window in seconds
• limit: Maximum number of actions allowed within that time window
• Multiple rate limit windows can be specified (up to 6)

Examples:

// Allow 10 messages per 60 seconds, 40 messages per 300 seconds
"ratelimit": {
  "message": "60:10,300:40"
}

// Allow 5 calls per 10 seconds, 20 calls per minute, 100 calls per hour
"ratelimit": {
  "call": "10:5,60:20,3600:100"
}

// Hourly, daily, weekly limits
"ratelimit": {
  "upload": "3600:50,86400:200,604800:1000"  // 50/hour, 200/day, 1000/week
}

// Empty value = unlimited
"ratelimit": {
  "location": ""  // No rate limit
}

Rate Limit Rules

1. Ascending Duration: Each time window must be larger than the previous one
2. Duration Ratio: Each duration must be at most 30 times the previous duration
3. Ascending Limits: Each limit should generally be higher than the previous one (though not strictly enforced)
4. Maximum Windows: Up to 6 rate limit windows can be specified
5. Optimization: The system may slightly adjust the specified limits for optimization purposes. View the final applied limits in the API response

Valid Examples:

"10:5,30:15,60:25"           // ✓ Each duration is 2-3x previous
"60:10,300:40,3600:200"      // ✓ Durations are 5x and 12x previous
"10:5,300:100,3600:500"      // ✓ Second duration is 30x first (maximum allowed)

Invalid Examples:

"10:5,5:10"                  // ✗ Second duration (5) is smaller than first (10)
"10:5,400:20"                // ✗ Second duration (400) is 40x first (exceeds 30x limit)
"10:20,30:10"                // ⚠ Limits decreasing (not recommended but allowed)

Rate Limit Windows - Use Cases

The flexible rate limiting system allows you to create limits that suit your application's needs:

• Burst Prevention: 10:5,60:20 - Limit sudden spikes (5 per 10s) while allowing reasonable sustained use (20 per minute)
• Hourly Limits: 3600:100 - Simple hourly cap
• Daily Limits: 86400:1000 - Daily usage cap
• Weekly Limits: 604800:5000 - Weekly usage cap
• Tiered Limits: 60:10,3600:200,86400:1000 - Combine short-term burst control with long-term usage limits
• Monthly Limits: 2592000:50000 - ~30 day usage cap

You can mix and match time windows to create the rate limiting strategy that best fits your application's usage patterns.

Parameters

Rate Limit Examples

Free Tier - Basic Usage:

"ratelimit": {
  "message": "60:20,3600:500,86400:2000",     // 20/min, 500/hour, 2000/day
  "call": "3600:10,86400:30",                 // 10 calls/hour, 30/day
  "upload": "3600:20,86400:100",              // 20 uploads/hour, 100/day
  "location": "60:5,3600:100,86400:500",      // 5/min, 100/hour, 500/day
  "login": "60:3,600:10",                     // 3/min, 10/10min
  "failure": "60:5,600:10"                    // 5 failures/min, 10/10min
}

Premium Tier - Normal Usage:

"ratelimit": {
  "message": "60:50,3600:2000,86400:10000",   // 50/min, 2000/hour, 10k/day
  "call": "3600:50,86400:200",                // 50 calls/hour, 200/day
  "upload": "3600:100,86400:500",             // 100 uploads/hour, 500/day
  "location": "60:10,3600:300,86400:2000",    // 10/min, 300/hour, 2000/day
}

Business/Enterprise Tier - High Volume:

"ratelimit": {
  "message": "60:100,3600:5000,86400:50000",  // 100/min, 5k/hour, 50k/day
  "call": "3600:200,86400:1000",              // 200 calls/hour, 1000/day
  "upload": "3600:500,86400:5000",            // 500 uploads/hour, 5k/day
  "location": "",                              // Unlimited for fleet tracking
}

Anti-Spam/Trial Users:

"ratelimit": {
  "message": "60:5,3600:50,86400:200",        // Strict spam prevention
  "call": "3600:3,86400:10",                  // Very limited calls
  "upload": "3600:5,86400:20",                // Minimal uploads
  "location": "3600:20,86400:100",            // Limited location updates
}

Note: Always check the response to see the final rate limits applied by the system, as they may differ slightly from your input for optimization purposes.

Location Parameters

Control location features and privacy settings:

General Location Settings

User Location Settings

Group Location Settings

Location Subscription Settings

Proximity Search Parameters

Control proximity search capabilities:

User Search Settings

Group Search Settings

Response

If the request is successful, the response will be:

{
  "uac": {
    "id": 1,
    "platforms": "",
    "features": { ... },
    "message": { ... },
    "presence": { ... },
    "call": { ... },
    "conf": { ... },
    "group": { ... },
    "file": { ... },
    "location": { ... },
    "proximity_search": { ... },
    "ratelimit": { ... },
    "peers": 0,
    "app": { ... }
  },
  "op": "uacset",
  "result": true
}

The response includes the complete UAC configuration with all settings.

Deleting a UAC Configuration

To delete an existing UAC configuration, send the following JSON request:

{
  "op": "uacdel",
  "token": "your-app-token",
  "uac": {
    "id": 4,
    "unlink": 1
  }
}

Assigning UAC to Users

Once you have created a UAC configuration, you can assign it to users using the User Management API by setting the uac parameter in useradd or userset request. You can set it to default by setting UAC 0 or 1 (app default).

During User Creation

{
  "op": "useradd",
  "token": "your-app-token",
  "user": {
    "address": "user@example.com",
    "name": "Premium User",
    "uac": {
      "id": 3,
      "expiry": 0,
      "fallback": 2
    },
    "token": {
      "appid": "com.example.app",
      "expiry": 525600
    }
  }
}

Modifying Existing User

{
  "op": "userset",
  "token": "your-app-token",
  "user": {
    "uid": 123,
    "uac": {
      "id": 3
    }
  }
}

Notes

• UAC configurations are applied when users connect to mesibo services
• Changes to UAC configurations affect all users assigned to that UAC ID immediately
• Setting a parameter to 0 typically disables that feature
• Omitted parameters use default values
• Available UAC ID ranges:
  • Free Plan: 1-4 (4 configurations)
  • Cloud/On-Premise: 1-64 (64 configurations)
• Platform-specific UACs allow up to 64 × 6 = 384 different configurations

Temporary UAC Assignment with Expiry

mesibo allows you to assign a UAC to a user with an expiry time, after which the user automatically falls back to a different UAC. This enables temporary feature access scenarios such as trial periods, promotional upgrades, time-limited subscriptions, or temporary feature unlocks.

Use Cases

Trial Periods:

• Give new users premium features for 7 days, then revert to free tier
• Offer extended trial for users who complete onboarding

Promotional Upgrades:

• Weekend promotion: Premium features for 48 hours
• Holiday special: Unlock features for a limited time

Time-Limited Subscriptions:

• Monthly premium access that auto-expires
• Seasonal subscriptions (e.g., 3-month summer pass)

Temporary Feature Access:

• Reward users with 24-hour premium access for achievements
• Grant temporary group calling during events
• Time-boxed location sharing for specific use cases

Grace Periods:

• Allow premium features for 3 days after subscription expires
• Provide extended access during payment processing

How It Works

When assigning a UAC with expiry:

1. User is assigned primary UAC (e.g., Premium - UAC 3)
2. Expiry time is set (e.g., 7 days from now)
3. Fallback UAC is specified (e.g., Free - UAC 2)
4. After expiry time, user automatically switches to fallback UAC

Hierarchy:

• Before expiry: User has primary UAC features
• After expiry: User automatically gets fallback UAC features
• No manual intervention needed

Assigning UAC with Expiry

Use the User Management API to assign a UAC with expiry:

{
  "op": "userset",
  "token": "your-app-token",
  "user": {
    "uid": 123,
    "uac": {
      "id": 3,              // Premium UAC
      "expiry": 604800,     // Expires in 7 days (seconds)
      "fallback": 2         // Falls back to Free UAC
    }
  }
}

Parameters

Notes:

• uac.expiry is specified in seconds from now (not absolute timestamp)
• If uac.fallback is not specified, user falls back to default UAC (ID 1) after expiry
• Setting uac.expiry to 0 or omitting it means no expiry (permanent assignment)
• The expiry happens automatically - no API calls needed

Examples

Example 1: 7-Day Trial for New Users

{
  "op": "useradd",
  "token": "your-app-token",
  "user": {
    "address": "newuser@example.com",
    "name": "New User",
    "uac": {
      "id": 3,           // Premium features
      "expiry": 604800,  // 7 days (7 * 24 * 60 * 60)
      "fallback": 2      // Free tier after trial
    },
    "token": {
      "appid": "com.example.app",
      "expiry": 525600
    }
  }
}

Result: User gets 7 days of premium features, then automatically switches to free tier.

Example 2: Weekend Promotion (48 Hours)

{
  "op": "userset",
  "token": "your-app-token",
  "user": {
    "uid": 456,
    "uac": {
      "id": 3,           // Premium features
      "expiry": 172800,  // 48 hours (2 * 24 * 60 * 60)
      "fallback": 2      // Back to free tier
    }
  }
}

Result: User gets weekend premium access, automatically reverts to free tier on Monday.

Example 3: Monthly Subscription

{
  "op": "userset",
  "token": "your-app-token",
  "user": {
    "uid": 789,
    "uac": {
      "id": 4,            // Monthly premium
      "expiry": 2592000,  // 30 days (30 * 24 * 60 * 60)
      "fallback": 2       // Free tier after 30 days
    }
  }
}

Result: 30-day premium access, then automatic revert to free tier.

Example 4: Achievement Reward (24 Hours)

{
  "op": "userset",
  "token": "your-app-token",
  "user": {
    "uid": 321,
    "uac": {
      "id": 5,           // Special features UAC
      "expiry": 86400,   // 24 hours
      "fallback": 2      // Regular tier
    }
  }
}

Result: 24-hour special feature access as achievement reward.

Example 5: Grace Period After Subscription Ends

{
  "op": "userset",
  "token": "your-app-token",
  "user": {
    "uid": 555,
    "uac": {
      "id": 3,          // Premium features
      "expiry": 259200, // 3 days grace period (3 * 24 * 60 * 60)
      "fallback": 2     // Free tier
    }
  }
}

Result: 3-day grace period with premium features before downgrading.

Example 6: Permanent Assignment (No Expiry)

{
  "op": "userset",
  "token": "your-app-token",
  "user": {
    "uid": 999,
    "uac": {
      "id": 4,          // Premium UAC
      "expiry": 0       // No expiry (or omit this parameter)
      // fallback not needed
    }
  }
}

Result: Permanent premium access, no automatic expiry.

Common Expiry Durations

Renewing or Extending Access

To extend a user's temporary UAC before it expires:

{
  "op": "userset",
  "token": "your-app-token",
  "user": {
    "uid": 123,
    "uac": {
      "id": 3,           // Same UAC or different
      "expiry": 604800,  // New expiry time (from now)
      "fallback": 2
    }
  }
}

Note: The new uac.expiry is always calculated from the current time, not from the previous expiry.

Checking Current UAC Assignment

Use the userget API to check a user's current UAC assignment and expiry:

{
  "op": "userget",
  "token": "your-app-token",
  "user": {
    "uid": 123
  }
}

Response:

{
  "user": {
    "uid": 123,
    "uac": {
      "id": 3,
      "expiry": 345600,     // Remaining seconds until expiry
      "fallback": 2
    }
    // ... other user fields
  },
  "op": "userget",
  "result": true
}

Best Practices

1. Always specify fallback: Set uac.fallback to ensure users have a defined experience after expiry
2. Clear communication: Inform users about trial/promotion duration and what happens after
3. Renewal reminders: Send notifications before UAC expires to encourage upgrades
4. Grace periods: Consider 1-3 day grace periods for expired subscriptions
5. Monitor usage: Track which temporary features drive conversions
6. Test thoroughly: Verify expiry behavior with short test durations (e.g., 60 seconds)

Implementation Tips

For Trial Conversions:

// Day 1: Assign trial
uac: {id: 3, expiry: 604800, fallback: 2}  // Premium for 7 days, then free

// Day 5: Send reminder about 2 days left

// Day 7: Auto-expires to free tier

// If user subscribes: Update to permanent premium
uac: {id: 3, expiry: 0}  // No expiry

For Promotional Campaigns:

// Start promotion
uac: {id: 4, expiry: 172800, fallback: 2}  // Promo features for 48 hours

// During promotion: Track feature usage

// After expiry: Offer discount based on usage

For Subscription Management:

// On subscription purchase
uac: {id: 3, expiry: 2592000, fallback: 2}  // 30 days

// 5 days before expiry: Send renewal reminder

// On renewal: Extend for another 30 days
uac: {id: 3, expiry: 2592000, fallback: 2}

// If not renewed: Auto-downgrades to free tier