Remove the collaborator from Matomo | OpsBlu Docs

Remove the collaborator from Matomo

How to revoke user access and offboard team members from Matomo. Covers account deletion, API key revocation, partial access removal, and security.

Remove User Access

Follow this process when a collaborator should no longer access your Matomo instance. Properly offboarding users protects your analytics infrastructure from unauthorized activity, maintains compliance with data governance policies, and ensures continuity of tracking and reporting workflows.

Removing a user from Matomo can be permanent. Once deleted, you cannot restore their login credentials, custom segments, scheduled reports, or goals they created. Always transfer ownership of critical assets and document the removal before proceeding.

When to Remove Users

Remove Matomo access when:

  • An employee leaves the organization (resignation, termination, or retirement).
  • An agency or consultant contract ends and they no longer manage analytics.
  • A user changes roles and no longer requires Matomo access.
  • Security or compliance teams request removal due to policy violations or audit findings.
  • A temporary contractor's project concludes and their access is no longer needed.
  • The user has been inactive for 90+ days and your organization enforces periodic access reviews.
  • Data privacy or legal requests removal to ensure GDPR, CCPA, or other regulatory compliance.
  • Their site scope reduces to zero and they no longer need access to any sites.
  • SSO/LDAP provisioning removes the user from the identity provider group.
  • Infrastructure changes require limiting access to self-hosted Matomo servers.

Deactivation Triggers

Common triggers that should prompt immediate user removal:

  • Employee termination: Revoke access on the same day to prevent unauthorized data viewing, export, or configuration changes.
  • Contract termination: Remove agency or consultant users within 24 hours of contract end.
  • Role change: If an analyst transitions to a non-analytics role, remove their Matomo access entirely.
  • Security incident: If credentials are compromised or suspicious activity is detected, immediately remove access and rotate tokens.
  • Quarterly access review: Remove users who haven't logged in for 90+ days or are no longer with the organization.
  • Site migration: If all sites a user had access to are migrated to another Matomo instance, remove the user.
  • LDAP/SSO removal: If removed from the IdP group, manually verify they can no longer access Matomo.
  • Super User reduction: If Super User access was granted temporarily, revoke it when the project completes.

Pre-Removal Assessment

Before removing a user, complete this assessment to avoid disrupting analytics workflows:

Identify owned assets

Check whether the user owns or created:

  • Custom segments: User segments they created for analysis or reports
  • Scheduled reports: Email reports or PDF exports they configured
  • Goals and conversions: Goal definitions they set up for tracking
  • Custom dashboards: Dashboard widgets or layouts they created
  • Annotations: Event annotations they added to reports
  • Alert configurations: Email alerts or thresholds they set up
  • Tag Manager containers: Tags, triggers, or variables they created in Matomo Tag Manager
  • Data layer tracking: Custom tracking configurations they implemented
  • API tokens: token_auth keys they use for integrations or exports
  • Custom dimensions: User-defined dimensions they configured
  • Server configurations: If self-hosted, any server-level access or database credentials they manage

Transfer ownership

For each asset identified:

  1. Go to the asset settings (segment, report, goal, dashboard).
  2. Change the Owner field to an active Admin or appropriate team member.
  3. For scheduled reports, reassign the sender email to another user.
  4. For tag manager containers, transfer ownership to another tag manager admin.
  5. For custom segments, export them and import under a new owner if platform doesn't support transfer.
  6. Document the transfer in your ticketing system with the new owner's name.

Critical: Do not skip asset transfer. If you delete a user who owns scheduled reports or custom segments, those assets may become inaccessible or stop functioning, disrupting stakeholder reporting.

Review site access

  1. Navigate to Administration → System → Users and open the user's account.
  2. Review all sites they have access to and their permission level for each.
  3. Document whether they have:
    • View access: Can view reports
    • Write access: Can create/edit segments, goals, reports
    • Admin access: Can manage site settings
    • Super User access: Full platform control
  4. Identify if they're the only Admin or Super User for any site (requires designating a replacement).
  5. Check if they manage ecommerce tracking, log analytics, or other specialized modules.

Confirm approval

Obtain written approval from:

  • The user's manager or department head
  • HR or Finance if due to termination or contract end
  • Security, Compliance, or Legal if part of an audit or data privacy requirement
  • Infrastructure or DevOps if user has server-level access to self-hosted Matomo
  • Data governance lead if user managed tracking plans or data quality

Save the approval email or ticket for your access log.

Removal Steps

Once you've completed the pre-removal assessment:

Step 1: Access user management

  1. Sign in to Matomo as a Super User or Admin with user management privileges.
  2. Navigate to Administration → System → Users (or Administration → Users depending on Matomo version).
  3. Locate the user in the users table.
  4. You can use the search or filter functionality to find them by username or email.

Step 2: Review current access

  1. Click on the user's name or Edit icon.
  2. Review their current:
    • Global permissions (Super User, Admin, etc.)
    • Site-specific permissions (which sites, what roles)
    • token_auth value (if visible)
    • Last login date (if tracked)
  3. Screenshot this page for your access log before making changes.
  4. Note any plugin-specific permissions (Tag Manager, Heatmaps, etc.).

Step 3: Remove site permissions (optional partial removal)

If the user should lose access to specific sites but remain active on others:

  1. In the Permissions section, find the sites they should no longer access.
  2. Change their permission to No Access or remove the site entirely from their list.
  3. Save the changes.
  4. Document which sites were removed and why.

This is useful when a contractor's scope narrows to specific sites only.

Step 4: Downgrade from Super User (optional)

If the user should lose Super User access but retain site-level access:

  1. Uncheck the Super User checkbox.
  2. Assign appropriate site-level permissions instead.
  3. This removes their ability to:
    • Manage other users
    • Access all sites
    • Configure plugins and system settings
    • Access server logs or database
  4. Save the changes.

Step 5: Full user deletion

If the user should be completely removed from Matomo:

  1. From the users table, find the user's row.
  2. Click Delete or the trash icon next to their name.
  3. Matomo will prompt you to confirm the deletion.
  4. Confirm by clicking Yes or Delete User.
  5. The user will immediately lose access to all sites and the Matomo platform.
  6. Their username and email will be removed from the system.

Note: If SSO/LDAP provisions the account, also remove them from the IdP group to prevent automatic re-provisioning.

Step 6: Revoke API tokens

Even after deleting a user, their token_auth may still work for API calls:

  1. Navigate to Administration → Platform → API or Administration → System → Personal Security.
  2. Find and delete any API tokens associated with the user's account.
  3. If using older Matomo versions, the token_auth is tied to the user and should be invalidated upon deletion, but verify in your API logs.
  4. Update any integrations or scripts using the old token_auth to use a service account or shared token.

Step 7: Verify removal

  1. Refresh the Users page and confirm the user no longer appears.
  2. Search for their username or email to ensure no duplicate accounts exist.
  3. Check that scheduled reports and segments were successfully transferred to new owners.
  4. Screenshot the updated Users list showing the user removed.
  5. Test that the user can no longer log in (if feasible).

Step 8: Remove server-level access (self-hosted only)

For self-hosted Matomo instances, also remove:

  • SSH access: Remove their public key from authorized_keys or user account from the server
  • Database access: Revoke MySQL/PostgreSQL user credentials they may have used
  • File system access: Remove FTP/SFTP accounts or shared directory permissions
  • Server monitoring: Remove from Nagios, Datadog, or other monitoring tools
  • Backup access: Revoke access to backup storage or restoration tools

Post-Removal Tasks

After removing the user:

Rotate credentials

If the user had access to sensitive credentials:

  • API tokens: Regenerate any shared token_auth values or API secrets.
  • Database credentials: Rotate MySQL/PostgreSQL passwords if they had DB access.
  • SSH keys: Remove their public keys from all Matomo servers.
  • Integration tokens: Update third-party integrations (data warehouses, BI tools, etc.) that used their credentials.

Document which credentials were rotated and notify affected teams.

Update documentation

  • Access log: Record user email, date removed, reason, approver name, assets transferred, credentials rotated.
  • SSO/LDAP system: Remove the user from any Matomo-related groups in your identity provider.
  • Internal roster: Update your team roster, org chart, or RACI matrix.
  • Runbooks: Update any documentation that referenced the removed user as a contact or owner.
  • Infrastructure docs: Update server access lists, VPN configs, or firewall rules if applicable.

Notify stakeholders

  • Inform the user (if appropriate) that their Matomo access has been revoked.
  • Alert new asset owners that they now own scheduled reports, segments, or goals.
  • Update the analytics team via Slack or email that the user no longer has access.
  • Notify infrastructure team if server-level access was removed.
  • Inform report recipients if scheduled reports will come from a new sender.

Audit remaining users

  • Scan the Users table for other accounts that may need removal or downgrade.
  • Flag users with Super User access who no longer require it.
  • Identify users who haven't logged in recently (check activity logs or database).
  • Review API tokens and remove any orphaned or unused tokens.

Review audit logs

  1. Navigate to Administration → System → Audit Log (if available in your Matomo version or via plugin).
  2. Filter by the removed user's username or IP address.
  3. Review their recent activity:
    • Reports viewed or exported
    • Configuration changes (goals, segments, site settings)
    • User management actions
    • Plugin installations or updates
  4. Export the audit log entries and archive them with your compliance records.

Schedule next review

  • Add the removal to your quarterly access review log.
  • Set a reminder to review all Matomo users in 90 days.
  • Include Matomo access in onboarding/offboarding checklists.
  • Update access review spreadsheet or CMDB.

Emergency Removal Procedures

For immediate security threats (compromised credentials, malicious activity, data breach):

  1. Immediately delete the user without waiting for asset transfer.
  2. Revoke all token_auth and API tokens the user had access to.
  3. Change database passwords if they had direct database access.
  4. Review audit logs for suspicious activity:
    • Mass data exports
    • Goal or tracking code deletions
    • User permission escalations
    • Plugin installations
    • Configuration changes that could expose data
  5. Check server logs (for self-hosted) for unusual access patterns or file modifications.
  6. Notify security team and infrastructure admin immediately.
  7. Document the incident with timestamps and screenshots.
  8. Transfer asset ownership after the emergency removal.
  9. File incident report with security, compliance, and legal teams.
  10. Consider IP banning or firewall rules if external access is involved.

Troubleshooting

Cannot delete user because they own active segments:

  • Transfer ownership of all segments first using the segment export/import feature.
  • Reassign scheduled reports to another user.
  • Then retry deletion.

User was deleted but can still log in:

  • Check if they have multiple accounts (different username/email).
  • Verify they were actually deleted from the database (check matomo_user table if self-hosted).
  • If using SSO/LDAP, ensure they were removed from the IdP group.
  • Clear Matomo's cache and session storage.
  • Contact Matomo support if the issue persists.

Need to restore a deleted user:

  • Deletion is permanent; you cannot restore the user account from Matomo UI.
  • If self-hosted, you may restore from a database backup (requires DBA skills).
  • Otherwise, create a new user and manually recreate their segments and reports.

User removed from LDAP but still has Matomo access:

  • LDAP provisioning may have a sync delay; wait 15-30 minutes and check again.
  • Manually delete the user from Matomo if LDAP deprovisioning isn't working.
  • Verify LDAP sync configuration and check sync logs.

Scheduled reports stopped sending after user removal:

  • Scheduled reports may be tied to the deleted user's account.
  • Recreate reports under an active user or shared service account.
  • Update email configurations to use a shared sender address.

API calls still work after user deletion:

  • Old token_auth may not be invalidated immediately in some Matomo versions.
  • Manually revoke tokens via Administration → Platform → API.
  • Update any applications using the old token.
  • Check database matomo_user_token_auth table if self-hosted.

Self-hosted: Cannot access Matomo after removing last Super User:

  • Access the MySQL/PostgreSQL database directly.
  • Update the matomo_access table to grant Super User to another account.
  • Or create a new Super User via the ./console CLI tool: ./console usersmanager:set-super-user username

Best Practices

  • Remove access on the same day as termination or contract end, ideally within hours.
  • Always transfer asset ownership before deleting to avoid broken reports and segments.
  • Screenshot before and after every removal for compliance documentation.
  • Run quarterly access reviews to catch stale accounts and unused licenses (for Matomo Cloud).
  • Document every removal with date, reason, approver, and assets transferred.
  • Revoke API tokens separately from user deletion to prevent continued API access.
  • Use service accounts for integrations and scheduled reports instead of individual user credentials.
  • Maintain at least 2 Super Users to prevent lockouts.
  • For self-hosted: Separate server access from Matomo UI access in your documentation.
  • Audit regularly: Review user permissions quarterly and remove unnecessary Super User access.

Common Use Cases

Employee termination

  1. Receive termination notification from HR with effective date
  2. Review user's current Matomo access and owned assets
  3. Document all segments, reports, goals, and tag manager configs they created
  4. Transfer ownership to their manager or designated replacement
  5. Delete the user from Matomo
  6. Revoke all token_auth and API tokens
  7. If self-hosted: Remove SSH access, database credentials, and server monitoring access
  8. Export audit logs for compliance
  9. Document removal with HR ticket reference
  10. Update team roster and access documentation

Agency or consultant contract ends

  1. Confirm contract end date with procurement or project manager
  2. Review which sites and assets they have access to
  3. Transfer ownership of segments, reports, goals, and tag manager containers to internal team
  4. Document all integrations or API connections they configured
  5. Delete user from Matomo
  6. Revoke any shared API tokens or database credentials
  7. If self-hosted: Remove server access and any infrastructure credentials
  8. Update vendor contact list and access matrix
  9. Document removal with contract reference
  10. Conduct knowledge transfer session with internal team if needed

Role change to non-analytics role

  1. Confirm the role change with HR or manager
  2. Assess if any read-only access is needed for reporting purposes
  3. Transfer ownership of all segments, reports, and goals they created
  4. If no access needed: Delete user completely
  5. If read-only needed: Change all site permissions from Write/Admin to View only
  6. Remove Super User access if they had it
  7. Revoke API tokens used for integrations
  8. Document the change with role change effective date
  9. Update team documentation and org chart

Quarterly access review cleanup

  1. Export current Users list from Matomo
  2. Cross-reference against HR roster and active employees
  3. Generate login activity report (from database or audit logs)
  4. Identify users who:
    • Left the organization
    • Haven't logged in for 90+ days
    • No longer require Matomo access based on current role
    • Have excessive permissions (Super User when site-level access is sufficient)
  5. For each user to remove:
    • Review owned assets and transfer if needed
    • Document reason for removal
    • Delete user and revoke tokens
  6. Export updated Users list and compare to original
  7. Document all removals in quarterly access review report
  8. Present findings to security, compliance, or data governance team
  9. Update access review schedule for next quarter

Security incident response

  1. Security team identifies compromised credentials or suspicious Matomo activity
  2. Immediately delete the user from Matomo
  3. Revoke all API tokens associated with the user
  4. Change database and server passwords if they had infrastructure access
  5. Review audit logs for unauthorized activity:
    • Data exports or report downloads
    • Goal or tracking code deletions
    • Site configuration changes
    • Plugin installations or updates
    • User permission escalations
  6. Check server logs (if self-hosted) for:
    • Unusual login locations or times
    • Failed authentication attempts
    • File system modifications
    • Database queries
  7. Document all suspicious activity with timestamps and screenshots
  8. Transfer asset ownership after emergency removal
  9. Report findings to:
    • Security team and CISO
    • Compliance and legal teams
    • Data privacy officer
    • Infrastructure team
  10. Update incident response documentation
  11. Implement additional security controls:
    • Enable 2FA for all users
    • Restrict IP access
    • Implement stronger password policies
    • Add rate limiting to API

SSO/LDAP deprovisioning

  1. User is removed from LDAP group or SSO identity provider
  2. Verify LDAP sync removes them from Matomo automatically (check sync logs)
  3. If manual removal needed, delete user from Matomo
  4. Confirm user can no longer authenticate via SSO/LDAP
  5. Document removal with LDAP/SSO change reference
  6. Audit other SSO-provisioned accounts for accuracy
  7. Test SSO deprovisioning workflow to ensure it's working correctly

Self-hosted: Server administrator offboarding

  1. User with server-level access to Matomo infrastructure is leaving
  2. Follow standard Matomo user removal process first
  3. Remove SSH access:
    • Delete their user account from the server
    • Remove their public key from ~/.ssh/authorized_keys
    • Update sudo access lists
  4. Rotate database credentials:
    • Change MySQL/PostgreSQL root password
    • Update Matomo's config.ini.php with new credentials
    • Revoke any DB user accounts they created
  5. Update server access:
    • Remove from VPN access lists
    • Update firewall rules if they had special permissions
    • Revoke monitoring tool access (Nagios, Datadog, etc.)
  6. Rotate backup credentials:
    • Change backup storage passwords
    • Update backup script credentials
    • Revoke access to offsite backup locations
  7. Review and update:
    • Cron jobs or scheduled tasks they created
    • Custom scripts or automation
    • SSL certificate management access
  8. Document all infrastructure changes
  9. Notify infrastructure team and update runbooks
Nach oben