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 POST requests and will not be valid when used as a URL parameter for a GET request. It is recommended to create POST 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
- In 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 POST 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 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.