Managing users with the API (advanced)

Cloud On-Premise

The Matomo UsersManager API provides a complete set of methods to manage users, roles, and permissions programmatically. This is especially useful for organisations that integrate Matomo with other systems, synchronise users and want to automate user management workflows.

Available UsersManager actions

The API allows you to create and manage users, assign and revoke permissions, and retrieve user information. Some of the most commonly used API methods include:

  • UsersManager.addUser: Create new users.
  • UsersManager.updateUser: Update existing users.
  • UsersManager.deleteUser: Remove users.
  • UsersManager.inviteUser / .resendInvite: Invite users by email.
  • UsersManager.setUserAccess: Set permissions (view, write, admin, no access).
  • UsersManager.getUsersWithSiteAccess: Lists all users who have access to the specified site.
  • UsersManager.getUsersSitesFromAccess: List all users by permission type.
  • UsersManager.getUsers / .getUser / .getUserByEmail: List users.
  • UsersManager.getUsersHavingSuperUserAccess: List all Superusers.`
  • UsersManager.getAvailableRoles: Roles define what a user can do within a given site in Matomo. They are the standard permission levels applied across most of Matomo’s features such as Superuser, admin, view, and write.
  • UsersManager.getAvailableCapabilities: Capabilities are feature-specific rights primarily used for Matomo Tag Manager (MTM). For example, tagmanager_write to manage containers, tags, triggers, variables.
  • UsersManager.addCapabilities / .removeCapabilities: Manage capabilities.

To see a full list of available methods and parameters, explore the UsersManager API documentation.

Access the UsersManager API

The UsersManager API is part of your Matomo instance. All requests are sent to your Matomo base URL with /index.php appended.

  1. You can try out calls directly in your browser for simple read requests, or use tools like curl, Postman, or scripts in languages such as PHP or Python to integrate them into your workflows.
  2. For quick access, open the Matomo user interface and go to Matomo settings (Administration) Settings Cog Icon > Export > API.
  3. Many API methods are listed with ready-made examples in XML or JSON format. Open one of these links to see how the request URL is structured, for example: https://your-matomo.example/index.php?module=API&method=UsersManager.getUsersWithSiteAccess&format=xml&token_auth=123

Structure of the API request

Every call to the UsersManager API follows the same structure. You send a request to your Matomo instance with specific parameters that tell Matomo what action to perform, who it applies to, and how to authenticate the request.

Understanding this structure makes it easier to build your own calls or adapt the examples provided.

1. Endpoint

Every API call is made against your Matomo base URL with /index.php appended.

2. Module and method

All requests must include module=API. The method parameter then specifies the exact action you want to perform, such as UsersManager.getUsersWithSiteAccess.

  • Read-only methods (those beginning with get) can be called with either GET or POST, since they only return information.
  • Write methods (such as addUser, updateUser) should use POST. This ensures parameters are passed securely.

3. Parameters

Provide the required parameters for the chosen action. Common ones include:

  • userLogin refers to the target user’s login.
  • access defines one of view, write, admin, or noaccess.
  • idSites sets one site ID, a comma-separated list, or all.

4. Authentication

Requests to the UsersManager API require a valid token_auth with Superuser rights. Read more on how to generate the token.

Example 1: Create a new user

The following examples show how you can build the API request:

Create a new user with login bob, email bob@example.com, and assign initial site access.

  • The user is created with no access to any site unless you specify initialIdSite and grant them a role.
  • If you pass only initialIdSite=10 (without explicitly setting access), the user gets view access for that site by default.
curl -X POST "https://your-matomo-domain.example/index.php" \
  -d "module=API" \
  -d "method=UsersManager.addUser" \
  -d "userLogin=bob" \
  -d "password=SecurePass123" \
  -d "email=bob@example.com" \
  -d "initialIdSite=1" \
  -d "token_auth=YOUR_SUPER_USER_TOKEN"

Example 2: Invite a new user by email

This example shows how to send an invitation to create a new Matomo account for newuser@example.com. The method used generates an invite link that is sent to the specified email address.

By default, the invited user receives view access to the initialIdSite specified. The expiryInDays parameter controls how long the invite link remains valid (default is 7 days).

curl -X POST "https://your-matomo-domain.example/index.php" \
  -d "module=API&method=UsersManager.inviteUser" \
  -d "userLogin=newuser" \
  -d "email=newuser@example.com" \
  -d "initialIdSite=10" \
  -d "expiryInDays=7" \
  -d "token_auth=YOUR_AUTH_TOKEN"

Test the UsersManager API safely with a read-only call such as UsersManager.getUsers to confirm your authentication token and endpoint are working. It is recommended to test calls in a staging environment before applying them to production.

For a full reference of available APIs, refer to the developer documentation.

Previous FAQ: Manage users