Set up OAuth 2.0 authentication for the Matomo API FAQ - How to

Matomo includes the OAuth 2.0 authentication feature that allows external applications to securely access the Matomo API on behalf of a superuser. Unlike fixed authentication tokens, OAuth 2.0 issues short-lived access tokens and refresh tokens. Instead of relying on static credentials, OAuth 2.0 enables safer integrations while maintaining control over what data is accessed and improves security by:

reducing the risk of long-term credential exposure.
eliminating the need to share permanent authentication tokens or passwords.
supporting user-level permissions and explicit consent.
allowing OAuth 2.0 clients to be paused or resumed at any time to control access.
providing a standard and widely-adopted method for secure third-party integrations.

This guide explains how to configure OAuth 2.0 in Matomo.

How the OAuth 2.0 process works

The OAuth 2.0 authentication flow allows an external application to request access to the Matomo API, receive temporary credentials, and use them to make authorised API requests. The OAuth 2.0 process typically follows these steps:

1. Create and authorise an OAuth client: A Matomo superuser will need to register an application (client) that requests access to Matomo. The superuser then reviews the request and grants permission for the application. These permissions are defined using scopes, such as read or write access.

2. Use the authorisation code: After the superuser approves the request, Matomo redirects the application to the configured callback URL and includes a temporary authorisation code. The application sends this code to Matomo to obtain an access token. The application then includes the access token when making requests to the Matomo API. Note: The callback URL is the endpoint where Matomo redirects the user after they authorise the application. This URL receives the authorisation code, which the application then exchanges for an access token.

3. Refresh the token when it expires: Access tokens should be short-lived, for example, configured to expire after 10 minutes. When an access token expires, the application uses a refresh token to request a new access token without requiring the user to authorise again. Users do not enter the access token manually. After authorisation, Matomo issues the token directly to the client application, which uses it automatically when making API requests. OAuth 2.0 replaces the older workflow where you had to copy a permanent token_auth value.

4. Pause or resume the OAuth client when needed: You can can pause an OAuth client to temporarily stop it from accessing the API. Access can be resumed at any time without reconfiguring the client. This provides additional control over integrations without needing to revoke or recreate credentials.

Permission scopes in OAuth 2.0

The allowed permission scope defines the maximum access level granted to the OAuth token. For example, if the admin scope is used, the token will have admin-level access at most, even if the authenticated user is a superuser:

read (view) access to analytics data.
write access for configuration or management actions.
admin access that includes both read and write permissions.
superuser permissions includes all operations.

The application can only perform actions that are allowed by the approved scope.

Manage OAuth 2.0 settings

To access the OAuth 2.0 settings in Matomo, navigate to Administration > System > General settings > OAuth 2.0.

For Access token lifetime (seconds), specify how long an access token remains valid after it is issued. After this time expires, the client must use a refresh token to obtain a new access token.
For Refresh token lifetime (seconds), specify how long a refresh token remains valid. While the refresh token is valid, the client can use it to request new access tokens without requiring the user to authorise again.
For Authorisation code lifetime (seconds), specify how long the authorisation code remains valid after it is issued during the OAuth authorisation process.
Enable authorisation code grant (PKCE supported) allows applications to obtain an access token after a user authorises the client. PKCE support adds an additional security layer and is recommended for public clients such as mobile or browser-based applications.
Enable client credentials grant allows server-to-server applications to request an access token using the client ID and client secret, without requiring user authorisation.
Enable refresh tokens allows clients to request a new access token when the current one expires, without requiring the user to authorise the application again.
Select the Allowed scope available for OAuth clients to request when authorising access to the Matomo API.
Click Save to update the changes.

How to configure OAuth 2.0 in Matomo

The OAuth 2.0 feature is designed for integrations such as mobile applications or external services that need secure access to Matomo data. For example, a mobile app can request access to a user’s Matomo account, retrieve analytics data through the API, and securely refresh its access token when required.

Create the client (application)

In OAuth 2.0, a client is an application that requests access to a user’s Matomo data. Before an application can interact with the Matomo API, you must register it as an OAuth client. During registration, Matomo generates credentials that the application uses for authentication.

Log in to Matomo as a superuser and open Administration from the top menu.
In On-Premise, navigate to Platform > OAuth 2.0, or
In Matomo Cloud, navigate to Export > OAuth 2.0.
Enter a Name that identifies the application requesting access to Matomo. This name appears on the user consent screen and in the list of OAuth clients.
Add a short Description to explain the purpose of the OAuth client, such as the system, integration, or application that will use it.
Select the client type based on where the application runs and whether it can securely store a client secret.
- Confidential: Use for server-side applications that can securely store a client secret. (Optional) If the client type is set to Confidential, you can copy the client secret when its generated. Note the client secret is only shown once.
- Public: Use for applications such as mobile or browser apps that cannot securely store secrets.
Select one or more OAuth authentication methods this client can use to obtain access tokens from Matomo. Available options include:
- Authorisation code: Used when an application requests authorisation before accessing the API.
- Client credentials: Used for server-to-server access without user interaction.
- Refresh token: Allows the client to automatically request a new access token when the current token expires.
Specify which API permissions the client can request when obtaining an access token. The permissions granted to issued tokens cannot exceed the scopes defined here.

Client Credentials flow (server-to-server)

The Client Credentials flow is an OAuth 2.0 authentication method used when a backend service needs to access the Matomo API without user interaction. In OAuth terminology, this method is called the Client Credentials grant, which allows an application to authenticate using its own credentials instead of requesting permission from a user. Typical use cases include::

Internal analytics dashboards
Scheduled data exports
Backend integrations

Use the following token request with your Matomo URL and client secret.

curl -X POST 'https://matomo.example.com/index.php?module=OAuth2&action=token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials' \
  -d 'client_id=analytics_app' \
  -d 'client_secret=123abc456Def' \
  -d 'scope=matomo:read'

After completing the OAuth 2.0 configuration, applications can authenticate with Matomo using the OAuth 2.0 protocol instead of using an authentication token. This allows secure, controlled access to the Matomo API based on the scopes defined in the integration settings.

Manage OAuth clients

After OAuth 2.0 clients are created in Matomo, you can manage them from Administration Platform > OAuth 2.0 > Manage OAuth 2.0 clients page. This page provides an overview of all configured clients, including their status (active or inactive), allowed grant types, client ID, and configured redirect URIs.

From this page, you can control how each client interacts with the Matomo API. Available actions include pausing or resuming access, editing client settings, deleting clients, or creating a new client.

Pause/resume OAuth 2.0 client

You can pause an OAuth 2.0 client to temporarily prevent it from accessing the Matomo API. Click the pause icon and the client will be marked with an inactive status. Any requests made using that client are no longer authorised. This is useful when you need to suspend access without deleting the client or changing its configuration.

You can resume the client at any time to restore access by clicking the play icon. This allows you to quickly re-enable integrations without requiring reauthorisation or creating a new client.

Next FAQ: What is the token_auth and where can I find this token to use in the API calls?