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

Cloud On-Premise

An authentication token (token_auth) lets applications authenticate with Matomo without using your account password. Tokens are used to retrieve reports through the Reporting API or send tracking requests that require authentication through the Tracking API.

Matomo 6

When creating an authentication token (token_auth), you can choose its Token access level to limit access. This lets you grant only the permissions needed for the token’s intended purpose.

To generate a token, follow these steps:

  1. Log in to Matomo and go to Administration admin gear icon> Personal > Security.
  2. Click Create New Token.
  3. Confirm your Matomo account password.
  4. Enter a Description explaining the token’s purpose.
  5. If you enable Only allow secure requests, the token can only be used in POST requests. It cannot be passed as a URL parameter in a GET request.
  6. Choose the Token access level that sets the highest permission the token can use: View, Write, Admin or Superuser. For example, a token restricted to View cannot perform actions that require Write or Admin access, even if your account has those permissions.
  7. You cannot grant permissions higher than your access level.
  8. Alternatively, select Inherit user access to use your account’s permissions instead.
    select token access level
  9. Set an Expiry date if you want the token to expire after a specified period. You will need to manually generate a new token after the expiry date.
  10. Click Create New Token to generate and save the token.
  11. Keep the token somewhere safe, such as a password manager. It is only displayed once. If you lose it, you will need to generate a new token.

Matomo 5

Authentication tokens (token_auth) automatically inherit the permissions of the user account that creates them. You cannot set a separate access level for an individual token.

To generate a token, follow these steps:

  1. Log in to Matomo and go to Administration admin gear icon> Personal > Security.
  2. Click Create New Token.
  3. Confirm your Matomo account password.
  4. Enter a Description explaining the token’s purpose.
  5. If you enable Only allow secure requests, the token can only be used in POST requests. It cannot be passed as a URL parameter in a GET request.
  6. Set an Expiry date if you want the token to expire after a specified period. You will need to manually generate a new token after the expiry date.
  7. Click Create New Token to generate and save the token.
  8. Keep the token somewhere safe, such as a password manager. It is only displayed once. If you lose it, you will need to generate a new token.

We recommend you create a new token for every app or purpose. This way, you can easily delete or regenerate the token for specific purposes and see which ones are still being used.

Understanding token behaviour with GET vs POST requests

When using the Matomo API for tracking or reporting, the way you send the token_auth affects whether authentication succeeds. The behaviour differs depending on whether your requests use GET or POST.

  • GET requests: the token is sent in the URL query string and it is not encrypted. Do not enable Only allow secure requests for tokens used in GET tracking requests. This is especially important when using integrations such as WooCommerce, Matomo for WordPress, or Looker Studio, which send tracking or reporting requests via GET. If the token is restricted to secure requests only, Matomo ignores it when received as a URL parameter, and the request fails to authenticate.
  • POST requests: the token is sent securely in the request body (assuming HTTPS) and you can safely enable these tokens as Only allow secure requests in Matomo. This setting is appropriate for API integrations that use POST requests, where the token is not exposed in the URL. Matching your token settings to the request method ensures secure and reliable authentication.

Matomo 4

To generate a token_auth follow these steps:

  1. Log in to Matomo.
  2. Go to Administration matomo admin gear icon > Personal > Security.
  3. Click on Create new token.
  4. Confirm your account password.
  5. Enter the description (purpose) for this token.
  6. Click on Create new token.

Matomo 3 and older

You can find the token_auth by logging into Matomo and navigating to Administration matomo admin gear icon in the top menu, then click the link API” in the left menu.

The token_auth value can be re-generated on request by any user > Personal > Security.

Matomo for WordPress

From version 5.3.0, Matomo for WordPress also supports the standard Matomo HTTP API, making it possible to connect with external tools like the Matomo mobile app and Looker Studio.