App Permissions

Goals

• Allow apps to integrate with the permissions system seamlessly.
• Provide out-of-the-box permission management for pre-installed apps and optionally for third-party apps.
• Enable permission enforcement via API.
• Maintain a clear separation from dynamic roles—apps should rely solely on permissions.

Assumptions

• Apps must not rely on roles (roles are dynamic).
• Apps are granted access to the permission domain and can query any permission by key and staff UID.
• Main focus: Pre-installed apps, though third-party apps can use system permissions or define their own.

Solution Flow

1. Partner builds an app.
2. Permission request is submitted using the App Permissions Request Form.
3. vcita team adds permissions - This process will typically take up to 30 days
4. When the Permissions UI is loaded, declared permissions for installed apps are displayed.
5. When checked, app permissions behave like regular permissions.
6. Permission enforcement is done using the shared permissions API.

APIs

Check Staff Permissions

GET /v3/access_control/staff_permissions?key[]=payment.export.manage&key[]=client.export.view

Parameters

• key[] – List of permission keys to check
• Max URL length: 2048 characters

Example Response

{
  "success": true,
  "data": [
    {
      "key": "clients.manage",
      "allow": true
    },
    {
      "key": "clients.clients_list.export",
      "allow": false
    }
  ]
}

Best Practices

• Use clear, scoped keys for app-specific permissions (e.g., finance.cashflow.view)
• Avoid reliance on roles
• Declare all required and manageable permissions in the app manifest
• Test permission filtering thoroughly in feature environments
• Use the StaffPermissions API to dynamically tailor app UI