Configure Access Control for Purpose-built Apps

Summary

Task: Set up extension permissions, multi-instance configurations, and granular access requirements

Time estimate: 20-30 minutes

Skill level: Advanced

Prerequisites

• Purpose-built App project deployed
• Understanding of Qualtrics permissions system
• Knowledge of your organization's access control needs
• Administrator access to configure permissions

Steps

Step 1: Understand Default Permission Model

All Purpose-built App extensions automatically receive two permissions:

1. Use Permission - Allows users to access and use the app
2. Configure Permission - Allows users to configure the app on the App Configuration page

For most use cases, these default permissions are sufficient.

Default permission flow:

If this meets your needs, no additional configuration is required. Skip to Step 6 to verify default permissions.

Step 2: Decide If Multi-Instance Configuration Is Needed

Multi-instance configuration allows brands to create multiple configurations of your Purpose-built App, each with separate:

• Branding and appearance
• Tab configurations
• User access (role-based)

Use multi-instance when:

• Large organizations need division-specific portals
• Different user groups need different tabs or data
• You want to provide the same app to multiple departments with separate configurations

Skip multi-instance when:

• Single-purpose app for entire organization
• Consistent configuration across all users
• Simpler permission model is preferred

Step 3: Enable Multi-Instance Configuration (If Needed)

Add multiInstanceConfiguration to your configurationSettings:

{
  "metadata": {
    "configurationSettings": {
      "configurable": true,
      "multiInstanceConfiguration": {
        "authType": "cxRoles"
      }
    }
  }
}

Key fields explained:

Field	Purpose	Value
authType	Authentication method for instances	"cxRoles" (recommended) or "roleService" (legacy)

Result: Admins can create multiple app instances:

Important: With multi-instance enabled, extension-level permissions are not sufficient to control access to individual instances. Admins must use role-based access control to determine who can access each instance.

For role management documentation, see Managing Dashboard Users.

Step 4: Configure Granular Requirements (Optional)

Most Purpose-built Apps do NOT need requirements

Access should typically be controlled by extension privileges or multi-instance role-based access.

Only use requirements if you need to restrict access based on specific Qualtrics account or brand permissions.

When to use requirements:

• Restrict entire app to users with specific Qualtrics features (e.g., only users with Vocalize access)
• Limit specific tabs to users with particular permissions
• Integrate with existing Qualtrics permission structures

App-level requirements (restrict entire app):

{
  "metadata": {
    "requirements": {
      "AccountPermissions": ["useVocalize"],
      "BrandPermissions": ["useCXActionPlanning"]
    },
    "tabs": [...]
  }
}

Tab-level requirements (restrict specific tabs):

{
  "metadata": {
    "tabs": [
      {
        "type": "content",
        "href": "/dashboard",
        "requirements": {
          "AccountPermissions": ["useAdvancedAnalytics"]
        }
      },
      {
        "type": "content",
        "href": "/reports",
        "requirements": {
          "BrandPermissions": ["useReporting"]
        }
      }
    ]
  }
}

Available permission types:

• AccountPermissions - User-level account permissions
• BrandPermissions - Brand-level feature permissions

Note: Content tabs often have their own empty states for users without access, so tab-level requirements are usually unnecessary.

To find appropriate permission values: Contact Qualtrics support for guidance on specific permissions.

Step 5: Combine Multi-Instance with Requirements (Advanced)

For maximum control, combine multi-instance configuration with granular requirements:

{
  "metadata": {
    "configurationSettings": {
      "configurable": true,
      "multiInstanceConfiguration": {
        "authType": "cxRoles"
      }
    },
    "requirements": {
      "BrandPermissions": ["useCXActionPlanning"]
    },
    "tabs": [
      {
        "type": "content",
        "href": "/dashboard",
        "requirements": {
          "AccountPermissions": ["useVocalize"]
        }
      }
    ]
  }
}

Access flow:

Step 6: Configure Extension Permissions in Qualtrics

After deploying your Purpose-built App:

1. Log in to Qualtrics as an administrator
2. Navigate to Admin → Extensions
3. Find your Purpose-built App extension
4. Click Permissions
5. Assign "Use" permission to appropriate users/groups
6. Assign "Configure" permission to administrators
7. Save changes

If using multi-instance:

1. Navigate to the App Configuration page
2. Create instances as needed
3. For each instance, configure role-based access
4. Assign users to appropriate roles

Step 7: Test Access Control

Test basic permissions:

1. Log in as a user with "Use" permission
2. Verify app appears and is accessible
3. Log in as a user without permission
4. Verify app does not appear

Test multi-instance access:

1. Create two instances with different role assignments
2. Assign User A to Instance 1 only
3. Assign User B to Instance 2 only
4. Verify each user sees only their assigned instance

Test granular requirements:

1. Log in as a user without required permissions
2. Verify app or tab is inaccessible
3. Log in with required permissions
4. Verify access is granted

Checkpoint: All access control rules should function as configured, with appropriate users gaining/losing access based on their permissions and roles.

Common Issues and Solutions

Issue: App Not Visible to Any Users

Symptoms: App doesn't appear for users with "Use" permission

Causes:

• App not enabled in configuration
• Requirements too restrictive
• Extension not properly activated

Solution:

Check app enabled state:

{
  "configurationSettings": {
    "defaultEnabledState": true  // Or manually enable in UI
  }
}

Verify requirements are appropriate:

// ❌ Too restrictive
"requirements": {
  "AccountPermissions": ["useRareFeature"]
}

// ✅ Appropriate for general access
// No requirements object, rely on extension permissions

Issue: Multi-Instance Not Available

Symptoms: Admins cannot create multiple instances

Causes:

• multiInstanceConfiguration not configured
• configurable: false
• Incorrect authType value

Solution:

Verify complete multi-instance configuration:

{
  "configurationSettings": {
    "configurable": true,  // ✅ Must be true
    "multiInstanceConfiguration": {
      "authType": "roleService"  // ✅ Required
    }
  }
}

Issue: Users See Wrong Instance

Symptoms: Users access instances they shouldn't have access to

Causes:

• Role assignments not configured
• Users assigned to multiple roles

Solution:

Review role assignments in Qualtrics Admin:

1. Navigate to instance configuration
2. Review assigned roles for each instance
3. Verify users are in correct roles only
4. Remove users from inappropriate roles

Issue: Tab Requirements Not Working

Symptoms: Users can access tabs despite missing permissions

Causes:

• Native Qualtrics pages show empty states instead of blocking access
• Requirements not properly configured

Solution:

For content tabs displaying native Qualtrics features, this is expected behavior. Qualtrics pages handle their own permission checking and show empty states or error messages.

Alternative approach: Use Custom Blocks instead of content tabs for tabs requiring strict access control.

Alternative Approaches

Simplified Single-Instance Model

For most apps, the simplest approach is best:

{
  "metadata": {
    // No configurationSettings - uses default permissions only
    "tabs": [...]
  }
}

Advantages:

• Simpler configuration
• Easier to manage
• Fewer potential issues
• Faster deployment

Custom Block-Based Access Control

For complex access control needs, use Custom Blocks with custom permission checking:

// In Custom Block
async function checkCustomPermissions() {
  const userRoles = await client.getUserRoles();
  if (!userRoles.includes('analytics-viewer')) {
    showAccessDeniedMessage();
    return false;
  }
  return true;
}

Advantages:

• Maximum flexibility
• Custom business logic
• Detailed audit logging
• Integration with external systems

Best Practices

Permission Strategy

• Start with default extension permissions
• Only add requirements when absolutely necessary
• Use multi-instance for organizational divisions, not for basic access control
• Document permission requirements clearly
• Test access control thoroughly before deployment

Multi-Instance Management

• Create clear naming conventions for instances
• Document which roles should access which instances
• Regularly audit instance assignments
• Remove unused instances
• Keep instance configurations synchronized where appropriate

Security

• Remember: UI restrictions are not security boundaries
• Use Qualtrics native permissions for true security
• Audit access regularly
• Log access attempts for compliance
• Follow principle of least privilege

Maintenance

• Review permission assignments quarterly
• Update requirements as Qualtrics features evolve
• Monitor for users with access issues
• Document access control decisions
• Plan for organizational changes

Recap

You've successfully configured access control for your Purpose-built App. Your app now has:

• Appropriate extension-level permissions
• Multi-instance configuration (if needed)
• Granular requirements (if needed)
• Role-based access control (if multi-instance)
• Tested and verified access rules

Your Purpose-built App now provides secure, appropriate access to the right users while maintaining flexibility for organizational needs.

Related Content

• Purpose-built App Deep Dive - Core concepts and architecture
• Enable User Configuration - Configuration settings
• Purpose-built App Command Reference - Complete configuration options
• Qualtrics Role Management - Managing dashboard users