Connecting Matomo to Stacktic

For: a Matomo Superuser. Takes about 5–10 minutes.

What this integration does

Connecting Matomo lets Stacktic see everyone with a login on your Matomo instance. When someone leaves, Stacktic can delete their account in one step. That takes away their ability to sign in and every site permission they had.

To connect, one person creates an API token in their own Matomo account. Matomo calls it a token_auth. Stacktic stores the token encrypted and only uses it with the instance URL you give it.

Stacktic needs two values:

Value	What it is
Matomo instance URL	The address you sign in to Matomo at. For a self-hosted instance, that's your own server. For Matomo Cloud, it's `https://yourorg.matomo.cloud`.
API token (`token_auth`)	An auth token created by a Superuser, from Administration → Personal → Security.

Before you start

You need to sign in as a Matomo Superuser, or get help from one. Someone who only runs a handful of sites isn't enough. A token from a non-Superuser will connect without an error. But Stacktic will only ever see the sites that person runs, not your whole instance's user list. Nothing in the product will tell you the list is incomplete.
You need the full instance URL, over https.
Be ready to pick an owner for this connection inside Stacktic. Matomo's API doesn't share an email address for the token itself, so Stacktic can't fill this in automatically.

Step 1: Create the API token in Matomo

Sign in to Matomo as a Superuser.
Go to your user icon → Administration → Personal → Security → Auth Tokens → Create New Auth Token.
Give it a name you'll recognize later, like "Stacktic."
Copy the token right away. Matomo shows it to you only once. If you leave the page before copying it, you'll need to create a new one.

Step 2: Connect in Stacktic

In Stacktic, go to Tools → Matomo → Integration and enter:

Matomo instance URL: the address from Step 1, for example https://analytics.yourcompany.com or https://yourorg.matomo.cloud. Stacktic ignores anything you type after the host.
API token (token_auth): the token you just copied.

Click Connect. Stacktic reads your instance's actual user list to check that the token and the URL work together. It doesn't just check that the token is valid in general. So a token that can sign in but can't read users still gets caught here.

Step 3: Turn on removal (when you're ready)

Stacktic starts reading who has access as soon as you connect. Deleting accounts during an offboarding is a separate switch. Because deletion is destructive and one-way, it's off by default. Turn on automatic removal on the integration when you want Stacktic to delete a departing person's Matomo account for you.

What you'll see

Once you're connected, Stacktic lists everyone your token can see. Each person is identified by their Matomo login, because Matomo has no separate display name. Next to each person:

Superuser: shown if they have instance-wide Superuser access. Otherwise nothing shows. Matomo doesn't report finer per-site view, write, or admin roles through this connection.
Last seen: from Matomo's own record of the person's last activity.

Two things don't show up, on purpose:

Pending invitations. Someone who's been invited but hasn't accepted yet isn't shown. An unaccepted invite isn't access.
A name for the connection itself. Matomo's API doesn't share any name for your instance beyond the URL you typed. So the connected card shows that URL, not a company or account name.

What removal does (and doesn't do)

Deleting someone's Matomo account through Stacktic removes their login and every site permission it had, right away.

Removal does not:

touch analytics data your sites have already recorded. That stays exactly as it is.
offer any way to undo the deletion. Matomo has no "reactivate" option. If you delete someone by mistake, you have to recreate the account from scratch.
work if the person being offboarded is the only Superuser on your instance. Matomo itself refuses that, just as it would if you tried it by hand. Someone else needs Superuser access first.

Security notes

The credential is personal. One person creates a token_auth, and it gets exactly their own permissions. Matomo has no separate service-account or instance-level token. If that person later leaves your company, the token goes away with their account, and this connection stops working. Stacktic flags this as a problem with the credential's owner, so someone can reconnect with a fresh token.
Superuser access matters, and Matomo won't warn you if it's missing. A token limited to some sites still connects fine. It just shows Stacktic part of your user list, with no error anywhere. Use a Superuser's token if you want Stacktic's picture of who has access to be complete.
Stacktic can't read the expiry date. You can create a Matomo token with or without an expiration date. But once the token exists, nothing in Matomo's API reports that date. So if you gave the token one, Stacktic asks you to enter it yourself on the connect screen. Then it can warn you before the connection quietly stops working.
Stored encrypted. Stacktic keeps only the instance URL and the token, both encrypted. It never shows the full token again. The connected card shows only its last 4 characters, next to the instance URL.
You can cut it off anytime. Delete the token in Matomo (Administration → Personal → Security → Auth Tokens) and the connection stops working right away.

Troubleshooting

Message in Stacktic	Likely cause and fix
"Matomo rejected the token ... it is wrong, revoked, or does not carry admin access."	The token was mistyped or revoked. Or it belongs to an account that has since lost admin access. Create a fresh token and reconnect.
"... is not a usable Matomo instance URL — give the full address over https ..."	The instance URL is missing `https://`, has a typo, or is otherwise malformed. Enter it again exactly as it appears in your browser when you're signed in to Matomo.
A brief, one-off failure that clears on its own	Stacktic couldn't reach your instance just now, because of a timeout or a temporary server error. Stacktic doesn't treat this as a bad token. Retry. If it keeps happening, check that your instance can be reached.
Offboarding removal fails: "There has to be at least one user with Super User access ..."	You're trying to delete your instance's only Superuser. Give Superuser access to someone else in Matomo first, then retry.
Offboarding removal reports the person wasn't found	They were already deleted, or never existed under that login. Stacktic counts this as done. You don't need to do anything.
The list in Stacktic looks smaller than your real user count	The connected token most likely belongs to someone who only runs some sites, not a Superuser. Reconnect with a Superuser's token to see everyone.

Frequently asked questions

Does this work if I only have a site-admin token, not a Superuser's? It will connect, but Stacktic will only see the sites that token's owner runs. It won't see your whole instance. No error tells you this is happening, so use a Superuser's token if you want the complete picture.

Will connecting delete or change anything right away? No. Connecting only reads your current user list. Stacktic deletes accounts only during an offboarding, and only after you turn on automatic removal.

What happens to analytics data when someone's account is deleted? Nothing. The data your sites have already recorded stays exactly as it is. Only the person's login and site permissions are removed.

Can a deleted account be undone? No. Matomo's deletion is one-way, and Matomo has no way to reactivate an account. If it turns out to be a mistake, you have to recreate the account from scratch in Matomo.

Does this work the same way for Matomo Cloud and a self-hosted instance? Yes. The only difference is the instance URL you enter. Use your own server's address for self-hosted, or https://yourorg.matomo.cloud for Matomo Cloud.

Does Stacktic show per-site roles, like who can edit a site vs. just view it? No. Matomo only reports whether someone has instance-wide Superuser access. Finer per-site view, write, and admin roles exist in Matomo, but they aren't shown here.