Export report instructions are unclear about public use of URL with token

[tbba]

Hi, I can get a widget code like this for embedding on a website:

_https://domain.de/matomo/index.php?module=API&format=HTML&idSite=1&period=day&date=2022-12-24,2023-01-22&method=API.get&filter_limit=100&format_metrics=1&expanded=1&token_auth=ENTER_YOUR_TOKEN_AUTH_HERE_

I found the instruction funny: The "Do not give the TOKEN away" warning, while this needs to be openly embedded as a GET variable?

_Replace ENTER_YOUR_TOKEN_AUTH_HERE in the export URL with your authentication token. 
Warning: Never give the URL with the real token to anyone._

I think this needs to be explained.

Matomo 4.13.1.

[bx80]

Hi @tbba,

Thanks for the feedback.

The token is specific to each user and for security reasons one user's token should not be shared with another user, however for the link to work the a user token does need to be included. The ENTER_YOUR_TOKEN_AUTH_HERE serves as a placeholder to help people see where to add their own token to the link.

You can read the original thinking behind this change here

The "Do not give the TOKEN away" warning is there for users with non-technical backgrounds for whom it might not be obvious that URLs containing security tokens should not be shared.

The full export report instruction reads:

"Note: To use the generated export URL, you will need to specify an app token auth. You can configure these tokens in [Admin → Security → Auths Tokens]. Replace ENTER_YOUR_TOKEN_AUTH_HERE in the Export URL by your Auth token. Warning: Never share the URL with the real token with anyone else."

Could you be a bit more specific about which part of this you think needs more explanation? Would a link to a step-by-step guide showing how to create a new token and update the URL be helpful?

[tbba]

Hi bx80, my comment only referred to the hint on your website near the example code:

With that GET token variable exactly the opposite of your hint is done, its published in public. Confusing.

I would find it interesting that someone can't do much with such a token. Maybe there could be a whitelist of websites where this token only works? The Google API (Google Maps) does it this way (token+whitelist).

[bx80]

Thanks for helping me understand the issue @tbba :+1:

For embedding widgets on a public website a token shouldn't be used, tokens should only be added to the URL for private or password protected pages as detailed in Requirements for embedding matomo reports

I agree that the instructions here aren't very clear and could result in people publishing their tokens on public websites, which could then be used to make API calls.

The export report hint needs to be updated to clearly delineate between using the export URL on a private website and a public website, it should probably reference the requirements for embedding FAQ too.

I'll assign this issue for prioritization.