In short. Authenticate automated Matomo exports with a generated token_auth sent in the body of an HTTPS POST request.
Definition: A Matomo authentication token, supplied as
token_auth, lets an application retrieve reports without sending the account password. As of October 2026, Matomo recommends a token restricted to POST requests, with the token in the request body.
Key facts
- Matomo's Reporting API Reference recommends POST-only tokens for API calls and warns against sharing URLs containing
token_auth. - Matomo's token authentication FAQ documents separate token access levels in Matomo 6; Matomo 5 tokens inherit their account's permissions.
- Matomo's Authentication In Depth guide explains that posting the token keeps it out of server URL logs.
Where is the export token created?
The token authentication FAQ gives the path Administration > Personal > Security > Create New Token. Creation requires password confirmation and a description of the token's purpose. Only allow secure requests restricts the token to POST use.
For Matomo 6, Token access level caps the token's permissions. A View token cannot perform actions requiring Write or Admin, even when its owner has those permissions. Matomo 5 uses the creating account's permissions for every token.
Matomo recommends a separate token for each application or purpose. The token appears only once; the FAQ suggests storing it in a password manager.
Which request method should the export use?
The Reporting API Reference documents URL-based authentication and recommends POST with token_auth in the body. This adapted example requests a visit summary in JSON, a structured data format:
curl -X POST \
'https://MATOMO_HOST/index.php?module=API&method=VisitsSummary.get&idSite=1&period=day&date=yesterday&format=json' \
-d 'token_auth=YOUR_TOKEN'
MATOMO_HOST and YOUR_TOKEN are placeholders. idSite=1 is an example website identifier; period=day&date=yesterday selects the previous day in that website's time zone. VisitsSummary.get selects the report.
Matomo's token authentication FAQ says POST sends the token in the body and assumes HTTPS for secure transmission. GET sends it in the URL query string. A token restricted by Only allow secure requests is ignored when received as a URL parameter, causing authentication to fail.
Why does a copied export link stop working?
Matomo's Authentication In Depth guide explains that force_api_session=1 makes an API call use a login session. Its token_auth is randomly generated at login and valid only for that session.
For an automated export, the Reporting API Reference instructs removal of force_api_session and replacement of the session token with a generated authentication token. That generated token can then be sent in the POST body.
Related terms
- How do I retrieve Matomo AI traffic reports through its API?
- Where do I find AI assistant traffic in Matomo?
- AI referral traffic
FAQ
Can I use GET for the export?
Yes, if your token permits URL-based use. Matomo's token authentication FAQ says a token with Only allow secure requests enabled fails authentication when supplied in the URL.
What happens when my token expires?
You need to generate a replacement manually. The same FAQ documents an optional Expiry date when creating a token.
Can I share the authenticated export URL?
Matomo's Reporting API Reference warns against sharing a URL containing token_auth: another person can use that token to fetch and change data within its permissions.
Sources
- Matomo, "Reporting API Reference", undated
- Matomo, "What is the token_auth and where can I find this token to use in the API calls?", undated
- Matomo, "Authentication In Depth", undated
Check how a page reads to answer engines. Open the GEO score analyzer