Update Matomo Roles for the collaborator

Overview

User permissions in Matomo require regular updates as project scopes evolve, team responsibilities shift, or security policies change. This guide covers the complete process for modifying user access, including role changes, site permission adjustments, and API token management.

Common Update Scenarios:

• Expanding access to new sites or properties
• Reducing permissions when project scope narrows
• Elevating roles for increased responsibilities
• Regenerating API tokens for security compliance
• Adjusting SSO/SCIM group mappings
• Implementing MFA requirements

When to Update Access

Trigger Events for Updates

1. Organizational Changes

   • New sites launched requiring analytics access
   • Team member promotion or role change
   • Project handoff between teams
   • Department restructuring
   • Contractor engagement scope modification

2. Security Requirements

   • Quarterly access reviews reveal over-provisioning
   • Compliance audit findings
   • Security incident requiring access restriction
   • New data classification policies
   • Password rotation schedules

3. Technical Changes

   • API integration requirements evolve
   • New plugins requiring admin permissions
   • Data pipeline modifications
   • Tag management system changes
   • Export/import needs

4. Access Expansion

   • Additional properties added to tracking
   • Cross-environment access (staging to production)
   • Scheduled report access required
   • Custom dashboard sharing needs
   • Integration with third-party tools

5. Access Reduction

   • Project completion
   • Feature development concluded
   • Temporary elevated access expiring
   • Security posture tightening
   • Least privilege enforcement

Matomo Permission Model

Global Roles

Super User:

• Complete platform control
• All plugin access
• System configuration rights
• User management capabilities
• Database-level access
• Recommended only for platform administrators

User (No Global Permission):

• Site-specific access only
• Permissions defined per property
• Cannot create users or modify system settings
• Most common role for collaborators

Site-Level Permissions

Permission Details:

• Admin: Full control over site including settings, goals, users, Tag Manager, and all features
• Write: Can create goals, segments, annotations, and scheduled reports but cannot modify site settings
• View: Read-only access to reports and dashboards
• No Access: Site not visible to user

Special Permission Scenarios

Tag Manager Access:

• Requires at least Write permission
• Admin for container settings and publishing
• Separate plugin permissions apply

Ecommerce Tracking:

• Accessible with View+ permissions
• Admin required to configure tracking settings
• Write to create conversion goals

Custom Dimensions/Variables:

• Admin required to create new dimensions
• View to see data in reports

Update Workflow

Step 1: Document Current Access

Before making changes, capture current state:

# Export current user access
# Matomo UI: Administration → System → Users
# or via API:
curl -X GET 'https://your-matomo.com/index.php?module=API&method=UsersManager.getUser&userLogin=collaborator@company.com&token_auth=YOUR_TOKEN&format=JSON'

Document:

• Current global role
• List of accessible sites with permissions
• API tokens in use
• SSO/SCIM group memberships
• Special permissions (Tag Manager, etc.)

Step 2: Obtain Approval

Follow your change management process:

1. Submit access change request with justification
2. Obtain manager/security team approval
3. Document business reason for change
4. Note expected duration (temporary vs permanent)
5. Record approver name and date

Approval Template:

User: collaborator@company.com
Change Type: Permission Update
Current Access: View on Site A, Write on Site B
Requested Access: Admin on Site A, View on Site B
Business Justification: Site A implementation project requiring Tag Manager configuration
Approver: [Manager Name]
Date: 2024-12-26
Duration: Permanent / Until [Date]

Step 3: Access Matomo User Management

Via Web UI:

1. Log in to Matomo with Super User or Admin account
2. Navigate to Administration (gear icon, top right)
3. Under System section, click Users
4. Locate the collaborator's account in the user list

Via API (for automation):

# List all users
curl 'https://your-matomo.com/index.php?module=API&method=UsersManager.getUsers&token_auth=YOUR_TOKEN&format=JSON'

# Get specific user
curl 'https://your-matomo.com/index.php?module=API&method=UsersManager.getUser&userLogin=USER_EMAIL&token_auth=YOUR_TOKEN&format=JSON'

Step 4: Update Global Role (If Needed)

To Grant Super User:

1. Find user in Administration → System → Users
2. Click Permissions next to their name
3. Check Super User checkbox
4. Confirm the change
5. User must log out and back in for changes to take effect

Warning: Super User grants complete system access. Only grant for:

• Platform administrators
• Implementation consultants requiring full config access
• Temporary debugging/migration scenarios

To Revoke Super User:

1. Uncheck Super User checkbox
2. Assign site-specific permissions (user won't have any by default)
3. Confirm user can no longer access system settings

API Method:

# Grant Super User
curl 'https://your-matomo.com/index.php?module=API&method=UsersManager.setSuperUserAccess&userLogin=USER_EMAIL&hasSuperUserAccess=1&token_auth=YOUR_TOKEN'

# Revoke Super User
curl 'https://your-matomo.com/index.php?module=API&method=UsersManager.setSuperUserAccess&userLogin=USER_EMAIL&hasSuperUserAccess=0&token_auth=YOUR_TOKEN'

Step 5: Update Site-Specific Permissions

Via Web UI:

1. In Administration → System → Users, click Permissions
2. You'll see a matrix of sites vs permission levels
3. For each site:
   • Admin: Check the box in Admin column
   • Write: Check the box in Write column
   • View: Check the box in View column
   • No Access: Uncheck all boxes for that site
4. Click Save at bottom of page

Permission Change Examples:

Scenario 1: Add new site access

• Locate new site row in permissions matrix
• Check appropriate permission level
• Save changes

Scenario 2: Reduce permissions

• Find site where reduction needed
• Uncheck higher permission
• Check lower permission (or uncheck all for no access)
• Save changes

Scenario 3: Elevate permissions temporarily

• Check higher permission level
• Document in calendar/ticket system for reversion date
• Set reminder to reduce permissions after period

Via API:

# Grant Admin access to site ID 1
curl 'https://your-matomo.com/index.php?module=API&method=UsersManager.setUserAccess&userLogin=USER_EMAIL&access=admin&idSites=1&token_auth=YOUR_TOKEN'

# Grant Write access to multiple sites
curl 'https://your-matomo.com/index.php?module=API&method=UsersManager.setUserAccess&userLogin=USER_EMAIL&access=write&idSites=1,2,3&token_auth=YOUR_TOKEN'

# Grant View access
curl 'https://your-matomo.com/index.php?module=API&method=UsersManager.setUserAccess&userLogin=USER_EMAIL&access=view&idSites=4&token_auth=YOUR_TOKEN'

# Revoke access (set to noaccess)
curl 'https://your-matomo.com/index.php?module=API&method=UsersManager.setUserAccess&userLogin=USER_EMAIL&access=noaccess&idSites=5&token_auth=YOUR_TOKEN'

Step 6: Regenerate API Tokens (If Needed)

When to Regenerate:

• Permission level increased (grant new capabilities)
• Security compliance requires rotation
• Suspected token exposure
• User offboarding from another system
• Quarterly/annual refresh policies

Regeneration Process:

1. Navigate to Administration → Personal → Security
2. Under Auth Tokens, click Delete for existing token
3. Click Create New Token
4. Provide description: "Collaborator API - Updated [Date]"
5. Copy token immediately (won't be shown again)
6. Securely share with collaborator via:
   • Password manager (1Password, LastPass)
   • Encrypted email
   • Secure file transfer
   • Team secrets vault

API Method:

# Regenerate token (creates new, doesn't delete old)
curl 'https://your-matomo.com/index.php?module=API&method=UsersManager.getTokenAuth&userLogin=USER_EMAIL&md5Password=MD5_HASH&token_auth=YOUR_SUPER_USER_TOKEN&format=JSON'

Important:

• Old tokens remain valid until explicitly deleted
• Update all integrations using the token
• Test new token before revoking old one
• Document which systems use each token

Step 7: Update SSO/SCIM Mappings (If Applicable)

If using SSO with group-based provisioning:

SAML/SSO Configuration:

1. Access your Identity Provider (Okta, Azure AD, Google Workspace)
2. Navigate to Matomo application settings
3. Update group mappings:
   • Matomo-SuperUser → Super User role
   • Matomo-Admin-SiteA → Admin on Site A
   • Matomo-View-All → View on all sites
4. Add/remove user from appropriate groups
5. Force sync or wait for next scheduled sync
6. Verify in Matomo that permissions updated

SCIM Provisioning:

If using automated provisioning:

1. User group membership changes propagate automatically
2. Check Administration → System → Users to confirm sync
3. SCIM logs in IdP show provisioning events
4. Typical sync time: 5-30 minutes

Manual Override:

Even with SSO/SCIM, you can manually override in Matomo:

• Changes persist until next sync
• Useful for temporary access
• Document that manual change may revert on sync

Step 8: Verify Changes

Verification Checklist:

1. Permission Matrix Check

   • Navigate to Administration → System → Users → Permissions
   • Verify all checkboxes match intended state
   • Screenshot for documentation

2. Collaborator Login Test

   • Request collaborator log out and back in
   • Verify they see expected sites in menu
   • Test report access on granted sites
   • Confirm no access to revoked sites

3. API Token Verification

   • Test new token with simple API call:

     curl 'https://your-matomo.com/index.php?module=API&method=SitesManager.getSitesWithAdminAccess&token_auth=NEW_TOKEN&format=JSON'
     

   • Verify response matches expected site access

4. Feature-Specific Testing

   • Tag Manager access (if Admin granted)
   • Goal creation (if Write granted)
   • Settings modification (if Admin granted)
   • Export capabilities
   • Custom dashboard access

5. Audit Log Review

   • Check Administration → System → Audit Log
   • Verify permission change events recorded
   • Export log entries for compliance documentation

Step 9: Communicate Changes

Notification Template:

To: collaborator@company.com
Subject: Matomo Access Updated - [Date]

Your Matomo analytics access has been updated as follows:

Previous Access:
- Site A: View
- Site B: Write

Updated Access:
- Site A: Admin
- Site B: View
- Site C: Write (newly added)

Changes Effective: Immediately (please log out/in to refresh)

API Token: [If regenerated] New token shared via [secure method]
  - Update integrations using old token by [deadline]
  - Old token will be revoked on [date]

Reason for Change: [Business justification]
Approved By: [Manager name]
Ticket Reference: [JIRA-123]

Questions? Contact: it-support@company.com

Access Review Date: [Next quarterly review]

Step 10: Document in IAM System

Record in your Identity & Access Management system:

{
  "user": "collaborator@company.com",
  "system": "Matomo Analytics",
  "change_type": "permission_update",
  "change_date": "2024-12-26",
  "changed_by": "admin@company.com",
  "approval_ticket": "JIRA-12345",
  "previous_access": {
    "global_role": "user",
    "sites": [
      {"id": 1, "name": "Main Site", "permission": "view"},
      {"id": 2, "name": "Blog", "permission": "write"}
    ]
  },
  "new_access": {
    "global_role": "user",
    "sites": [
      {"id": 1, "name": "Main Site", "permission": "admin"},
      {"id": 2, "name": "Blog", "permission": "view"},
      {"id": 3, "name": "Shop", "permission": "write"}
    ]
  },
  "api_token_regenerated": true,
  "next_review_date": "2025-03-26"
}

Special Update Scenarios

Temporary Elevated Access

Use Case: Implementation project requiring Admin access for 2 weeks

Process:

1. Grant elevated permissions (e.g., Admin)
2. Set calendar reminder for reversion date
3. Create ticket for automatic reversion
4. Notify collaborator of access expiration
5. On expiration:
   • Reduce permissions to original level
   • Notify collaborator of change
   • Archive project-specific dashboards/reports

Automation Option:

# Scheduled script to revert permissions
import requests
from datetime import datetime

REVERT_DATE = "2025-01-15"
if datetime.now().strftime("%Y-%m-%d") >= REVERT_DATE:
    # Reduce permissions
    requests.get(
        'https://your-matomo.com/index.php',
        params={
            'module': 'API',
            'method': 'UsersManager.setUserAccess',
            'userLogin': 'collaborator@company.com',
            'access': 'view',
            'idSites': '1',
            'token_auth': 'YOUR_TOKEN'
        }
    )

Bulk Permission Updates

Use Case: Granting view access to all production sites

Via API Script:

#!/bin/bash
USER_EMAIL="collaborator@company.com"
TOKEN="YOUR_SUPER_USER_TOKEN"
MATOMO_URL="https://your-matomo.com"

# Get all site IDs
SITES=$(curl -s "${MATOMO_URL}/index.php?module=API&method=SitesManager.getAllSitesId&token_auth=${TOKEN}&format=JSON" | jq -r '.[]' | tr '\n' ',')

# Grant view access to all sites
curl "${MATOMO_URL}/index.php?module=API&method=UsersManager.setUserAccess&userLogin=${USER_EMAIL}&access=view&idSites=${SITES}&token_auth=${TOKEN}"

Cross-Environment Synchronization

Use Case: Replicate production permissions to staging

Process:

1. Export production permissions:

   curl 'https://prod-matomo.com/index.php?module=API&method=UsersManager.getUsersPlusRole&token_auth=TOKEN&format=JSON' > prod_permissions.json
   

2. Parse and apply to staging:

   import json, requests
   
   with open('prod_permissions.json') as f:
       users = json.load(f)
   
   for user in users:
       if user['login'] == 'collaborator@company.com':
           for site_id, permission in user['sites'].items():
               requests.get(
                   'https://staging-matomo.com/index.php',
                   params={
                       'module': 'API',
                       'method': 'UsersManager.setUserAccess',
                       'userLogin': user['login'],
                       'access': permission,
                       'idSites': site_id,
                       'token_auth': 'STAGING_TOKEN'
                   }
               )
   

Emergency Access Revocation

Use Case: Security incident requires immediate access removal

Rapid Revocation:

1. Via UI:

   • Navigate to Users
   • Click Permissions
   • Uncheck all site access
   • Save immediately

2. Via API (fastest):

   # Revoke all access
   curl 'https://your-matomo.com/index.php?module=API&method=UsersManager.setUserAccess&userLogin=USER_EMAIL&access=noaccess&idSites=all&token_auth=YOUR_TOKEN'
   
   # Delete all auth tokens
   curl 'https://your-matomo.com/index.php?module=API&method=UsersManager.deleteUser&userLogin=USER_EMAIL&token_auth=YOUR_TOKEN'
   

3. Disable SSO access:

   • Remove from all IdP groups
   • Disable account in IdP

4. Verify:

   • Audit log shows revocation
   • Test login fails
   • API tokens return 401

5. Document incident:

   • Security ticket number
   • Revocation timestamp
   • Reason for emergency action
   • Re-enablement criteria

Validation & Testing

Post-Update Validation

1. Permission Matrix Verification

# Get user's current access
curl 'https://your-matomo.com/index.php?module=API&method=UsersManager.getSitesAccessFromUser&userLogin=USER_EMAIL&token_auth=YOUR_TOKEN&format=JSON'

Expected response:

{
  "1": "admin",
  "2": "view",
  "3": "write"
}

2. Functional Testing

Have collaborator test:

• Log in successfully
• See expected sites in site selector
• Access reports on granted sites
• Receive "access denied" on non-granted sites
• Create goals (if Write/Admin)
• Modify settings (if Admin)
• Access Tag Manager (if Admin)
• Export reports (per permission level)

3. API Token Testing

# Test new token
curl 'https://your-matomo.com/index.php?module=API&method=SitesManager.getSitesWithAdminAccess&token_auth=NEW_TOKEN&format=JSON'

# Should return sites with admin access only

4. Integration Testing

If collaborator uses integrations:

• Data warehouse exports
• Scheduled email reports
• Third-party tool connections
• Custom scripts/automation

Test each integration with updated permissions.

Troubleshooting

Changes Not Reflecting

Problem: User still sees old permissions after update

Solutions:

1. Have user log out and back in (clears session cache)
2. Clear browser cache/cookies
3. Wait 5 minutes for session timeout
4. Check if SSO sync overrode manual changes
5. Verify changes saved (check Audit Log)

API Token Not Working

Problem: New token returns authentication error

Solutions:

1. Verify token copied completely (no trailing spaces)
2. Check token belongs to correct user
3. Confirm user still has active account
4. Test with simple API call first
5. Regenerate if corruption suspected

Permission Escalation Not Effective

Problem: User granted Admin but can't access features

Solutions:

1. Verify permission saved (refresh user list)
2. Check if user needs plugin-specific permission
3. Confirm site is active (not archived)
4. Review feature flags or license limitations
5. Check browser console for JavaScript errors

SSO Sync Reverting Changes

Problem: Manual changes undone by SSO sync

Solutions:

1. Update group memberships in IdP
2. Use IdP-managed permissions (don't fight automation)
3. Temporarily disable SCIM sync for emergency overrides
4. Document sync schedule and plan changes around it

Security Best Practices

1. Least Privilege Principle

• Grant minimum permission level needed
• Review and reduce permissions regularly
• Temporary escalations must have expiration dates
• Document justification for every permission

2. Regular Access Reviews

# Quarterly Access Review Checklist

For each user:
- [ ] Still requires access? (Employment status, project status)
- [ ] Permission level still appropriate?
- [ ] All sites still needed?
- [ ] API tokens in use? (Revoke unused)
- [ ] SSO groups still correct?
- [ ] Last login date recent?
- [ ] Any compliance concerns?

Document findings and take action.

3. Separation of Duties

• No single user should have:
  • Admin access + financial data access
  • Production + staging admin rights (same person approving own changes)
  • User management + audit log deletion

4. Audit Trail Maintenance

Export audit logs regularly:

# Export last 90 days of user permission changes
curl 'https://your-matomo.com/index.php?module=API&method=PrivacyManager.exportDataSubjects&date=last90&filter_limit=-1&token_auth=YOUR_TOKEN' > audit_$(date +%Y%m%d).json

Store securely:

• Retain for minimum 1 year (check compliance requirements)
• Store in immutable/append-only storage
• Include in backup rotations
• Review monthly for unauthorized changes

5. Token Rotation Schedule

Recommended cadence:

• Super User tokens: Every 90 days
• Admin tokens: Every 180 days
• View/Write tokens: Annually or on permission change
• Emergency/incident: Immediate rotation

Automation:

from datetime import datetime, timedelta

def should_rotate_token(last_rotation_date, permission_level):
    days_since = (datetime.now() - last_rotation_date).days

    rotation_schedule = {
        'superuser': 90,
        'admin': 180,
        'write': 365,
        'view': 365
    }

    return days_since >= rotation_schedule.get(permission_level, 365)

Compliance Considerations

GDPR Requirements

When updating access:

• Document legal basis for data access
• Ensure user understands data protection obligations
• Record in Data Protection Impact Assessment (DPIA)
• Notify DPO if access to personal data granted

SOC 2 / ISO 27001

• Formal approval process required
• Access reviews every 90 days
• Automated provisioning/deprovisioning preferred
• Emergency access procedures documented
• All changes logged and reviewed

Industry-Specific (HIPAA, PCI-DSS)

HIPAA:

• Minimum necessary access principle
• Training required before access
• Audit log review quarterly
• Automatic suspension after 90 days inactive

PCI-DSS:

• Unique ID per user (no shared accounts)
• Revoke access within 24 hours of termination
• Review access privileges every 6 months
• Restrict admin access to few as possible

Documentation Requirements

Change Record Template

# Access Change Record

**Change ID:** UAM-2024-12-26-001
**Date:** 2024-12-26 14:30 UTC
**Changed By:** admin@company.com
**Approved By:** manager@company.com

## User Details
- Email: collaborator@company.com
- Department: Analytics Team
- Employment Type: Full-time employee

## Access Changes

### Before:
- Global Role: User
- Site 1 (Main Site): View
- Site 2 (Blog): Write

### After:
- Global Role: User
- Site 1 (Main Site): Admin
- Site 2 (Blog): View
- Site 3 (Shop): Write

## Justification
Implementation project for Site 1 Tag Manager configuration. Requires Admin access for container management and publishing. Project duration: 3 months.

## API Changes
- Token regenerated: Yes
- Old token revoked: 2024-12-27
- Integrations updated: Data pipeline (script updated 2024-12-26)

## Verification
- ✓ Permissions updated in Matomo
- ✓ User logged in and tested access
- ✓ API token tested successfully
- ✓ Audit log entry captured
- ✓ Notification sent to user

## Review Date
Next review: 2025-03-26 (3 months, end of project)

## Attachments
- approval_email.pdf
- audit_log_excerpt.pdf
- permission_matrix_screenshot.png

Related Tasks

After Updating Permissions

1. Update Documentation

   • Internal wiki/knowledge base
   • Team roster/contact list
   • Escalation procedures
   • Runbook references

2. Adjust Dependent Systems

   • Service account tokens in data pipelines
   • Scheduled report subscriptions
   • Dashboard sharing settings
   • Tag Manager container access
   • Third-party tool integrations

3. Review Other Platforms

   • If Matomo access changed, review:
     • Google Analytics access
     • Tag Manager permissions
     • BigQuery access
     • Data warehouse roles
   • Maintain consistent access levels

4. Update Training Materials

   • If new features accessible, provide training
   • Update onboarding documentation
   • Refresh user guides with new permissions
   • Schedule knowledge transfer sessions

Summary Checklist

Before completing an access update:

• Current access state documented
• Change approval obtained and recorded
• Global role updated (if applicable)
• Site permissions modified correctly
• API tokens regenerated (if needed)
• SSO/SCIM groups updated (if applicable)
• Changes verified through testing
• User notified of changes
• Audit log entry exported and stored
• IAM system updated with change record
• Next review date scheduled
• Dependent systems/integrations updated
• Documentation updated
• Compliance requirements met

Need to remove access entirely? See Remove User Access for complete offboarding procedures.

Setting up access initially? See Add User Access for onboarding workflows.