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

The token_auth acts as your password and is used to authenticate in API requests.

Security considerations

The token_auth is secret and should be handled very carefully: do not share it with anyone. Each Matomo user has a different token_auth.

From Matomo 5 it is possible to create tokens that can only be used in a secure way (via POST requests) and will not be valid when used as a URL parameter for a GET request. It is recommended to create ‘Secure only’ tokens to improve security.

Matomo 4 and newer

To generate a token_auth follow these steps:

  • Log in to Matomo
  • Go to the Matomo Admin through the top menu
  • Click on Personal -> Security
  • At the bottom of the page click on “Create new token”
  • Confirm your account password
  • Enter the purpose for this token
  • Choose if the token should only be valid for secure requests (Matomo 5 and newer)
  • Click on “Create new token”

You will now see the newly created token. Save it somewhere safe as you won’t be able to see it anymore once you leave that screen. For example, save it in a password manager. 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 etc.

Matomo 3 and older

You can find the token_auth by logging in Matomo (Piwik), then click on Administration 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 under Administration > Personal Settings.

Matomo for WordPress

The token_auth feature as well as Matomo’s HTTP Reporting API is not available in Matomo for WordPress because Matomo supports the WordPress REST API.

Previous FAQ: How do I find the website ID, also called idSite or Site ID?