Add a User to Matomo | OpsBlu Docs

Add a User to Matomo

Create or invite the collaborator account and assign site permissions in Matomo.

Use this workflow to grant the collaborator access to Matomo (cloud or on-premise).

Prerequisites

Before creating or inviting a user to Matomo, gather the necessary information and confirm your deployment model and permissions.

Required Information

  • Deployment Type: Determine whether you're using Matomo Cloud (SaaS) or a self-hosted instance, and confirm the base URL (e.g., yourcompany.matomo.cloud or analytics.yourcompany.com).
  • Site Access Requirements: List which websites (sites) in Matomo the collaborator should access, including production, staging, development, or specific brand/regional sites.
  • Service Account Details: Collect the collaborator's service account email address, username preference, and full name for the account profile.
  • Role Requirements: Review the statement of work to determine the appropriate permission level (View, Write, Admin, or Super User) for each site.
  • Engagement Scope: Confirm whether the collaborator needs access to goals, segments, ecommerce tracking, custom dimensions, or API capabilities.
  • Segments and Dashboards: Identify any specific segments, roll-up dashboards, or custom reports the collaborator should access or manage.

Permission Requirements

  • Super User Access: You must have Super User permissions in Matomo to create new users and assign site access. If you lack this role, escalate to your Matomo administrator.
  • Organization Admin (Cloud): For Matomo Cloud, Organization Admin privileges may be required to invite new users and manage billing-related settings.

SSO and LDAP Integration Considerations

If your organization uses SSO (SAML, OAuth) or LDAP authentication with Matomo:

  • Pre-Provision in Identity Provider: Create the user account in your IdP (Okta, Azure AD, Active Directory, etc.) before adding them in Matomo.
  • Group Mappings: Configure your SSO/LDAP group mappings to automatically assign Matomo roles based on IdP group membership. Common patterns include:
    • matomo-superuser → Super User role
    • matomo-admin → Admin role for specified sites
    • matomo-analyst → Write role for specified sites
    • matomo-viewer → View role for specified sites
  • SAML Attribute Mapping: Verify that user attributes (email, username, full name) are correctly mapped in your SAML configuration.
  • LDAP Synchronization: If using LDAP, confirm synchronization is working correctly and test with a temporary account if needed.

Self-Hosted Instance Considerations

For self-hosted Matomo deployments, additional planning is required:

  • Server Access: If the collaborator needs server-level access for log analytics, database queries, or plugin management, coordinate SSH and database credentials separately.
  • SMTP Configuration: Verify your email server configuration is working to send invitation and password reset emails. Test email delivery before inviting the user.
  • Password Policy: Review your organization's password complexity requirements and ensure the temporary password meets these standards.
  • Database Access: If the collaborator needs direct database access for advanced reporting or troubleshooting, plan separate MySQL/PostgreSQL user provisioning.

Security and Compliance Checklist

  • Access Request Approval: Obtain written approval from your project sponsor, data governance team, or security stakeholder as required by your organization's policies.
  • Data Classification: Confirm what types of analytics data the collaborator will access (PII, financial data, healthcare information, etc.) and whether Matomo sites contain sensitive data.
  • Privacy Compliance: Verify the collaborator's access aligns with GDPR, CCPA, HIPAA, or other applicable privacy regulations.
  • Audit Trail: Prepare to document the account creation in your IAM tracker, ITSM system, or compliance log with requester name, approval date, and business justification.
  • IP Restrictions: If Matomo access is restricted by IP address or VPN, coordinate with your network team before creating the account.

Understanding Matomo Roles and Permissions

Matomo provides a flexible permission system with site-specific and global roles.

Site-Specific Roles

Matomo permissions are assigned per website (site), allowing granular control:

View

Read-only access to reports and dashboards.

Capabilities:

  • View all reports, dashboards, and widgets for assigned sites
  • Access real-time visitor logs and individual visitor profiles
  • View segments, goals, and funnels
  • Export reports to PDF, CSV, or other formats
  • Cannot create or modify any configuration
  • Cannot access user management or site settings

When to grant View:

  • Collaborator performs reporting and analysis without configuration changes
  • Stakeholder needs visibility for oversight or compliance
  • Temporary access for auditing or review purposes
  • Read-only access satisfies engagement requirements

Typical use case: Analysts, stakeholders, and auditors who need data visibility without editing capabilities.

Write

Can create content and manage tracking configuration.

Capabilities:

  • All View permissions plus:
  • Create, edit, and delete goals and funnels
  • Manage custom dimensions and custom variables
  • Create, edit, and delete segments
  • Manage A/B tests and experiments
  • Configure ecommerce tracking parameters
  • Access Tag Manager (if enabled)
  • Cannot modify site settings or user permissions
  • Cannot install plugins or change platform configuration

When to grant Write:

  • Collaborator manages goals, conversions, and tracking plans
  • Engagement includes segment creation and audience analysis
  • Collaborator needs to configure A/B tests or experiments
  • Implementation work requires tag management capabilities

Typical use case: Implementation consultants, analytics practitioners, and marketing analysts managing tracking and conversion configuration.

Admin

Full control over site settings and configuration.

Capabilities:

  • All Write permissions plus:
  • Modify site settings (URLs, timezone, currency, ecommerce settings)
  • Manage site users and their permissions for that specific site
  • Install and configure site-specific plugins
  • Access and modify scheduled reports
  • Configure custom alerts and notifications
  • Manage site archives and historical data
  • Cannot access other sites or global Matomo settings
  • Cannot manage Super Users or platform-wide configuration

When to grant Admin:

  • Collaborator leads full implementation or site configuration
  • Engagement includes managing site settings, URLs, or timezone configuration
  • Collaborator manages site-specific integrations or plugins
  • Site-level user management is required

Typical use case: Implementation leads, site administrators, and analytics managers responsible for site configuration and team management.

Global Role

Super User

Complete control over the entire Matomo installation.

Capabilities:

  • All Admin permissions for all sites plus:
  • Create, edit, and delete websites (sites)
  • Manage all users and their permissions across all sites
  • Install, update, and configure plugins globally
  • Access system settings and configuration files
  • Manage Matomo updates and migrations
  • Configure system-wide integrations
  • Access database and diagnostic information
  • Modify security settings and privacy controls

When to grant Super User:

  • Collaborator manages the entire Matomo platform
  • Engagement includes platform administration, updates, or migrations
  • Collaborator needs to create new sites or manage global plugins
  • Very rarely needed for standard analytics consulting

Risks and considerations:

  • Highest privilege level with access to all data and settings
  • Can delete data, disable tracking, or misconfigure the platform
  • Can access database credentials and sensitive system information
  • Grant only when absolutely necessary and with strict oversight

Typical use case: Platform administrators, DevOps engineers managing Matomo infrastructure, or senior consultants managing full platform migrations.

Anonymous Access

Matomo also supports anonymous (public) access for specific sites:

  • Anonymous View: Allows unauthenticated users to view specific dashboards or reports via public URLs
  • Use case: Sharing reports with stakeholders who don't need Matomo accounts
  • Security consideration: Carefully control which sites and reports are publicly accessible
  • Configuration: Set per site in Administration → Websites → Manage

Invite or Create the Account

Follow these step-by-step instructions to create a Matomo user account.

Step 1: Navigate to User Management

For Matomo Cloud:

  1. Log into Matomo Cloud using an account with Organization Admin or Super User privileges
  2. Click the gear icon in the top-right corner to open Administration
  3. In the Platform section (left sidebar), select Users
  4. You'll see the current list of users with their roles and permissions

For Self-Hosted Matomo:

  1. Log into your Matomo instance using an account with Super User privileges
  2. Click Administration in the top navigation bar
  3. In the System section (left sidebar), select Users (under Users → Users)
  4. Review the current user list to confirm the collaborator doesn't already have access

Step 2: Initiate User Creation

For Matomo Cloud:

  1. Click Invite new user button in the top-right corner
  2. A dialog or form will appear for entering user details

For Self-Hosted Matomo:

  1. Click Add a new user button in the top-right corner
  2. You'll be directed to a user creation form

Step 3: Enter User Information

Complete the user profile fields:

  1. Username (Login):

    • Enter a unique username for the collaborator's account
    • Use a consistent naming convention (e.g., vendor.firstname.lastname or vendor-analytics)
    • Username cannot be changed after creation in most Matomo versions
    • Verify the username doesn't conflict with existing accounts

  2. Password (Self-Hosted Only):

    • For self-hosted Matomo, set a secure temporary password
    • Password should meet your organization's complexity requirements (typically 12+ characters, mixed case, numbers, symbols)
    • The collaborator will be prompted to change this password on first login
    • Document the temporary password securely to share with the collaborator
    • For Matomo Cloud: Password is set by the user when they accept the email invitation

  3. Email Address:

    • Enter the collaborator's service account email address
    • This email receives invitation, password reset, and notification messages
    • Verify the email address is correct to avoid delivery issues
    • For SSO/LDAP setups, ensure this matches the email in your IdP exactly

  4. Full Name (Optional but Recommended):

    • Enter the collaborator's full name or organization name
    • This appears in audit logs and helps identify users in the interface
    • Example: "Analytics Vendor - John Smith" or "Vendor Consulting Team"

Step 4: Assign Site Permissions

After creating the basic user profile, assign site-specific permissions:

  1. Select Sites:

    • You'll see a list of all websites (sites) in your Matomo instance
    • Check the box next to each site the collaborator should access
    • Consider organizing sites by production vs. staging, region, or brand to simplify selection

  2. Choose Role Per Site:

    • For each selected site, choose the appropriate role from the dropdown:
      • View: Read-only reporting access
      • Write: Goal management, segment creation, tracking configuration
      • Admin: Full site configuration and user management for that site
    • You can assign different roles to different sites (e.g., Admin for staging, View for production)

  3. All Websites Shortcut:

    • Some Matomo versions offer an "All Websites" option to grant the same role across all sites
    • Use this carefully - it includes future sites that haven't been created yet
    • For collaborators, typically assign specific sites rather than blanket access

Step 5: Configure Advanced Options

Depending on your Matomo version and configuration:

API Access (token_auth):

  • Matomo automatically generates a token_auth for each user upon creation
  • This token enables API access for data export, automation, and programmatic queries
  • To view/regenerate token_auth:
    1. After creating the user, edit their account
    2. Navigate to the Settings or Security tab
    3. Locate the Auth token section
    4. Copy the token to share securely with the collaborator
    5. Generate a new token if needed by clicking Regenerate
  • Store the token in a secure password manager or secrets vault
  • Never share tokens via unencrypted email or messaging platforms

Two-Factor Authentication (2FA):

  • If your Matomo instance requires 2FA, inform the collaborator about enrollment requirements
  • For self-hosted instances with 2FA plugins, the collaborator will need to configure 2FA on first login
  • Document 2FA enrollment process in your onboarding materials

Email Notifications:

  • Configure whether the user receives scheduled reports, alerts, or digest emails
  • For service accounts used for API access only, consider disabling notification emails

Step 6: Save and Confirm

  1. Review all entered information:

    • Username is correct and follows naming conventions
    • Email address is accurate
    • Site permissions match engagement scope
    • Role assignments are appropriate for each site
    • Temporary password meets security requirements (self-hosted)

  2. For Matomo Cloud:

    • Click Send Invitation to create the account and send invitation email
    • The user will receive an email with a link to set their password and activate their account

  3. For Self-Hosted Matomo:

    • Click Save or Add User to create the account
    • The user is immediately active with the temporary password you set
    • Matomo will attempt to send a welcome email if SMTP is configured

  4. Verify the user appears in the Users list with correct permissions

API Access and Token Management

Matomo's API enables programmatic access for data export, dashboards, and automation.

Understanding token_auth

  • token_auth is a 32-character hexadecimal string that authenticates API requests
  • Functions as a permanent API key associated with the user account
  • Grants the same permissions as the user has through the UI
  • Remains valid until manually regenerated or the user is deleted

Generating and Retrieving token_auth

For newly created users:

  1. Navigate to Administration → Users
  2. Click on the collaborator's username to edit their account
  3. Look for the Settings or Security section (location varies by Matomo version)
  4. Find Auth Token or token_auth field
  5. Copy the token to share with the collaborator

For existing users needing token regeneration:

  1. Edit the user account as described above
  2. Locate the Auth Token section
  3. Click Regenerate or Generate new token
  4. Confirm the regeneration (this invalidates the old token immediately)
  5. Copy the new token and share securely
  6. Update any scripts, integrations, or automations using the old token

Sharing Tokens Securely

  • Use encrypted communication channels (secure email, password managers with sharing features, or secrets management platforms)
  • Never send tokens via unencrypted email, Slack, Teams, or similar platforms
  • Document which systems and scripts use each token
  • Set expiration reminders for periodic token rotation (recommend every 90 days)

API Usage Examples

Once the collaborator has their token_auth, they can make API calls:

# Example: Retrieve visits and actions for today
https://your-matomo.example.com/?module=API&method=VisitsSummary.get&idSite=1&period=day&date=today&format=JSON&token_auth=YOUR_TOKEN_HERE

Common API use cases:

  • Exporting data to external dashboards or data warehouses
  • Automating report generation
  • Integrating Matomo data with business intelligence tools
  • Custom dashboard development
  • Scheduled data syncs

API Security Best Practices

  • Limit API tokens to the minimum required site access and role level
  • Create separate users for different API integrations rather than sharing tokens
  • Rotate tokens regularly (every 90 days recommended)
  • Monitor API request logs for unusual activity
  • Revoke tokens immediately when they're no longer needed or if compromised

SSO and LDAP Integration

Organizations using enterprise identity management should follow additional steps.

SAML/OAuth SSO Configuration

For Matomo Cloud with SSO:

  1. Configure SSO in Matomo:

    • Navigate to Administration → Platform → SSO
    • Configure your IdP settings (SSO URL, certificate, entity ID)
    • Map SAML attributes to Matomo user fields (email, username, display name)
    • Configure group-based role mappings if supported

  2. Create User in IdP First:

    • Add the user account to your identity provider
    • Assign them to the appropriate IdP groups that map to Matomo permissions
    • Verify the email address matches what you'll use in Matomo

  3. Invite or Create in Matomo:

    • Follow the standard user creation process in Matomo
    • Use the exact email address from your IdP
    • On first login, the user will authenticate through your SSO provider
    • Matomo will link the local account to the SSO identity

Role Mapping Conflicts:

  • If manual role assignment in Matomo conflicts with SSO group mappings, behavior varies by configuration
  • Test with a temporary account to understand which takes precedence
  • Document your organization's authoritative source (IdP vs. Matomo UI)

LDAP Integration (Self-Hosted)

For self-hosted Matomo with LDAP plugin:

  1. Install and Configure LDAP Plugin:

    • Install the LoginLDAP plugin via Administration → Marketplace
    • Navigate to Administration → System → LDAP Settings
    • Configure LDAP server connection (server URL, port, bind DN, password)
    • Set up user search filters and attribute mappings

  2. Configure Group Synchronization:

    • Map LDAP groups to Matomo roles and site access
    • Example: CN=matomo-analysts,OU=Groups,DC=company,DC=com → Write access to Site 1, 2, 3
    • Test group mapping with a temporary account

  3. Create User:

    • In some LDAP configurations, users are auto-created on first login
    • In others, you must manually create the user in Matomo first
    • Ensure the username matches the LDAP username exactly (typically the sAMAccountName or uid)

  4. First Login:

    • User navigates to your Matomo URL
    • Enters LDAP username and password
    • Matomo authenticates against LDAP server
    • User is granted access based on LDAP group memberships and Matomo role mappings

LDAP Troubleshooting:

  • Verify LDAP connection is working: Test in LDAP Settings page
  • Check LDAP logs for authentication failures
  • Confirm user's LDAP groups match expected Matomo role mappings
  • Test with a known-working LDAP account to isolate issues

Matomo Cloud vs. Self-Hosted Differences

Key differences in user management between deployment types.

Matomo Cloud

User Creation:

  • Invitation-based workflow sends email to user
  • User sets their own password via email link
  • Simpler onboarding with less manual credential sharing

Email Delivery:

  • Managed by Matomo Cloud infrastructure
  • Reliable delivery without SMTP configuration
  • Check spam folders if invitations aren't received

Organization Admin Role:

  • Matomo Cloud adds Organization Admin role for billing and organization management
  • Super User role still exists for analytics configuration
  • Organization Admin can manage billing, subscription, and organization settings

Automatic Updates:

  • Platform updates managed by Matomo
  • Plugin updates may still require user action
  • No server maintenance required

Self-Hosted Matomo

User Creation:

  • Direct account creation with manual password setting
  • Admin sets temporary password and shares securely
  • User prompted to change password on first login

Email Configuration:

  • Requires SMTP server configuration for email delivery
  • Test email delivery before inviting users
  • Manual credential sharing required if email fails

Server Access:

  • May require coordinating SSH, database, or file system access
  • Log Analytics requires server-level log file access
  • Plugin installation may require file system permissions

Update Management:

  • Administrators manually update Matomo core and plugins
  • Plan maintenance windows for updates
  • Test updates in staging environment before production

After Provisioning

After creating the user account, complete these steps to ensure successful onboarding.

Verify Account in Matomo

  1. Confirm User Appears in List:

    • Navigate to Administration → Users
    • Verify the collaborator's account appears with correct username and email
    • Check that site permissions and roles are correctly assigned
    • Note the user creation timestamp for your audit log

  2. Test Login (if possible):

    • If you can coordinate with the collaborator, have them log in to verify access
    • Confirm they see the expected sites in their site selector
    • Verify they can access reports and perform tasks appropriate to their role
    • For self-hosted: Confirm they're prompted to change the temporary password

  3. Verify API Token:

    • If API access is required, confirm the token_auth was generated
    • Copy the token for secure sharing with the collaborator
    • Test an API call with the token to verify it works

Share Essential Information

Provide the collaborator with comprehensive onboarding information:

  1. Login Details (Self-Hosted):

    • Matomo URL: https://analytics.yourcompany.com
    • Username: [username]
    • Temporary password: [password] (share securely, not via email)
    • Instructions to change password on first login

  2. Login Details (Matomo Cloud):

    • Matomo Cloud URL: https://yourcompany.matomo.cloud
    • Instructions to check email for invitation and set password
    • Note about checking spam/junk folders if invitation not received

  3. Site Access Information:

    • List of sites (websites) they can access with site IDs
    • Role assigned for each site (View, Write, Admin)
    • Links to key dashboards, reports, or segments they should review

  4. API Access (if applicable):

    • token_auth value (share via secure channel)
    • API documentation link: https://developer.matomo.org/api-reference
    • Examples of API calls relevant to their engagement
    • Rate limiting information (if applicable)

  5. Platform Context:

    • Matomo version (for self-hosted)
    • Installed plugins relevant to their work (Tag Manager, Heatmaps, A/B Testing, etc.)
    • Data retention settings
    • Timezone and currency settings for each site

  6. Technical Requirements:

    • VPN connection instructions (if required)
    • IP allowlist requirements (if applicable)
    • Browser compatibility notes
    • Two-factor authentication enrollment process (if required)

  7. Governance and Compliance:

    • Privacy policies affecting how analytics data can be used
    • Data handling requirements and classifications
    • Acceptable use policies
    • Incident reporting procedures for data quality or security concerns

Update Access Management Records

Document the account creation for audit and compliance purposes:

  1. IAM Tracker or Spreadsheet:

    • Record username, email, creation date, and assigned roles per site
    • Note the approver name and approval date
    • Reference the SOW, ticket number, or request ID
    • Set a review date based on engagement duration
    • Track token_auth generation and rotation schedule

  2. Ticketing System:

    • Update the access request ticket status to "Granted"
    • Attach screenshots of the Users page showing the new account
    • Document temporary password storage location (for self-hosted)
    • Link to related tickets (VPN access, server credentials, etc.)

  3. Compliance Logs:

    • Log the access grant in your GRC system if required
    • Include business justification and data classification
    • Note what sites and data the user can access

  4. Communication:

    • Send onboarding email to the collaborator with all necessary information
    • Notify project stakeholders that access has been granted
    • Update team wikis or runbooks with current user lists

First Login Checklist

When the collaborator logs in for the first time:

For Self-Hosted:

  • They'll be prompted to change the temporary password
  • New password must meet complexity requirements
  • They should see their assigned sites in the site selector
  • Reports should load without permission errors

For Matomo Cloud:

  • They click the invitation link from email
  • Set a password meeting requirements
  • Authenticate and access the platform
  • Verify site access and permissions

Both:

  • Bookmark the Matomo URL for easy access
  • Test viewing reports for assigned sites
  • Verify they cannot access sites they shouldn't see
  • Confirm role-appropriate capabilities (e.g., can create goals if Write access was granted)

Troubleshooting

Common issues when creating Matomo users and their resolutions.

Invitation Email Not Received (Matomo Cloud)

Symptoms: User reports they haven't received the invitation email.

Resolution Steps:

  1. Check Spam/Junk Folders:

    • Ask the collaborator to check spam, junk, and quarantine folders
    • Add @matomo.cloud to email allowlist

  2. Verify Email Address:

    • Confirm the email address entered is correct with no typos
    • Check the user record in Matomo to verify the displayed email

  3. Resend Invitation:

    • In Administration → Users, locate the user
    • Click Resend invitation if available
    • Alternatively, delete the pending user and recreate with the correct email

  4. Email Filtering:

    • Ask IT to check email gateway logs for messages from Matomo Cloud
    • Verify SPF/DKIM/DMARC records aren't blocking Matomo emails
    • Temporarily disable aggressive spam filters for testing

No Email Delivered (Self-Hosted)

Symptoms: Welcome or notification emails aren't being sent from self-hosted Matomo.

Resolution Steps:

  1. Verify SMTP Configuration:

    • Navigate to Administration → System → General Settings
    • Check SMTP server settings (server, port, authentication)
    • Send a test email using the "Send test email" feature

  2. Check Email Logs:

    • Review Matomo logs in tmp/logs/ for email-related errors
    • Check mail server logs for delivery failures or rejections

  3. Manual Credential Sharing:

    • If email cannot be fixed immediately, share credentials manually via secure channel
    • Document the temporary workaround and plan to fix SMTP configuration

  4. Use Alternative Email Plugin:

    • Consider installing SMTP plugin from Marketplace for better email delivery
    • Configure with service like SendGrid, Mailgun, or AWS SES

SSO Login Fails

Symptoms: User cannot log in via SSO, gets errors, or is redirected incorrectly.

Resolution Steps:

  1. Verify IdP Configuration:

    • Check SSO configuration in Administration → Platform → SSO
    • Verify certificate hasn't expired
    • Confirm SSO URL and entity ID are correct

  2. Check User Exists in IdP:

    • Confirm the user account exists in your identity provider
    • Verify email address matches exactly between IdP and Matomo

  3. Attribute Mapping:

    • Review SAML attribute mappings in Matomo SSO settings
    • Ensure email, username, and display name attributes are correctly mapped
    • Check IdP logs for attribute assertion details

  4. Group Membership:

    • Verify user is assigned to the correct IdP groups
    • Check that group mappings to Matomo roles are configured properly
    • Test with a known-working SSO account to isolate issues

  5. Browser Issues:

    • Clear browser cookies and cache
    • Try incognito/private browsing mode
    • Test with a different browser

LDAP Authentication Fails (Self-Hosted)

Symptoms: User cannot authenticate with LDAP credentials.

Resolution Steps:

  1. Test LDAP Connection:

    • Navigate to Administration → System → LDAP Settings
    • Use the built-in connection test feature
    • Verify server URL, port, and bind credentials

  2. Check Username Format:

    • Confirm the user is entering username in the expected format
    • Try both simple username and full DN (Distinguished Name)
    • Verify username matches LDAP attribute configured in settings

  3. Verify Group Membership:

    • Check user's LDAP groups match expected Matomo role mappings
    • Review LDAP group filter configuration
    • Query LDAP directly to verify user's group memberships

  4. Review LDAP Logs:

    • Check Matomo logs in tmp/logs/ for LDAP authentication errors
    • Review LDAP server logs for bind failures or search errors

  5. Manual User Creation:

    • Some LDAP configurations require manually creating the user first
    • Create user with matching username, then LDAP handles authentication

User Cannot See Expected Sites

Symptoms: User logs in successfully but doesn't see sites they should have access to.

Resolution Steps:

  1. Verify Site Permissions:

    • Navigate to Administration → Users
    • Edit the user account and review site access assignments
    • Confirm the correct sites are checked with appropriate roles

  2. Add Missing Sites:

    • If sites are missing, add them via the user edit page
    • Assign the appropriate role (View, Write, Admin)
    • Save changes and have the user refresh their browser

  3. Check Site Status:

    • Verify the sites aren't archived or deleted
    • Archived sites may not appear in the site selector for some users

  4. SSO/LDAP Override:

    • If using SSO or LDAP with group mappings, IdP groups may override manual assignments
    • Verify user is in the correct IdP groups for the intended sites
    • Check whether IdP or Matomo UI is the authoritative source for permissions

Super User Role Not Working as Expected

Symptoms: User has Super User role but can't access all features.

Resolution Steps:

  1. Verify Super User Assignment:

    • Navigate to Administration → Users
    • Check that the user has the Super User checkbox enabled
    • In some Matomo versions, Super User is a global flag, not a site-specific role

  2. Login with Correct Account:

    • Verify the user is logged in with the Super User account, not a different account
    • Check the username displayed in the top-right corner

  3. Browser Cache:

    • Clear browser cache and cookies completely
    • Log out and back in to refresh session permissions

  4. Plugin Restrictions:

    • Some plugins may restrict certain features even for Super Users
    • Check plugin settings and permissions

API Token Not Working

Symptoms: API calls with token_auth return authentication errors.

Resolution Steps:

  1. Verify Token:

    • Confirm the token is copied correctly with no extra spaces or characters
    • Check that the token matches what's shown in the user's account settings

  2. Check User Permissions:

    • Verify the user has appropriate site access and role for the API methods being called
    • API permissions match UI permissions - View role cannot modify goals via API

  3. Token Regenerated:

    • If the token was recently regenerated, old token is immediately invalid
    • Verify you're using the most recent token

  4. API Method Availability:

    • Some API methods require specific roles (Admin or Super User)
    • Review API documentation for method-specific permission requirements

  5. IP Restrictions:

    • Check if API access is restricted by IP address in Matomo configuration
    • Verify API calls originate from allowed IP ranges

Security and Compliance Best Practices

Follow these guidelines to maintain secure and compliant Matomo user management.

Principle of Least Privilege

  • Start with the most restrictive role (View) and escalate only when justified
  • Assign site access only for sites relevant to the engagement
  • Default to Write role for most implementation consultants; reserve Admin for those managing site settings
  • Grant Super User only in rare circumstances with strict oversight and time limitations

Regular Access Reviews

  • Conduct quarterly reviews of all Matomo users
  • Remove users who have completed their engagements
  • Verify site assignments still match current engagement scopes
  • Audit Super User accounts and downgrade when possible

Segregation of Duties

  • Separate production and staging/development site access when possible
  • Require different approval levels for Admin vs. Write access
  • Limit Super User role to 2-3 trusted administrators
  • Consider separate Matomo instances for staging and production if data sensitivity requires it

Password and Token Management

For Self-Hosted:

  • Enforce strong password policies (12+ characters, complexity requirements)
  • Require password changes on first login
  • Implement password expiration (90-180 days)
  • Enable two-factor authentication for all users (via plugin)

API Tokens:

  • Rotate token_auth every 90 days
  • Use separate users/tokens for different integrations
  • Revoke tokens immediately when no longer needed
  • Monitor API usage logs for anomalies

Audit Trail Maintenance

  • Document every user creation with justification, approver, and timestamp
  • Export user lists regularly for compliance archives
  • Leverage Matomo's activity log (if available) to track user actions
  • Integrate user provisioning with your organization's IAM or GRC systems

SSO and LDAP Security

  • Keep SSO certificates and LDAP bind credentials secure
  • Rotate SSO certificates before expiration
  • Monitor SSO/LDAP authentication logs for failed login attempts
  • Implement account lockout policies for repeated failures

Data Classification and Privacy

  • Assign site access based on data classification policies
  • Ensure user access complies with data processing agreements
  • Document what sites and data each user can access for GDPR/CCPA compliance
  • Apply privacy controls (IP anonymization, data retention limits) appropriate to data sensitivity
Back to top