How to get a Matomo API key

If you are working with us on a new custom dashboard, we will ask you for something we call your "API key" for Matomo. If you have never heard the term before, this guide is for you. We will explain exactly what an API key is, why we need it, and then walk you through getting one, one click at a time.

No technical knowledge is assumed. If you can log in to a website and click buttons, you can do this.

What is an API key, and why do we need it?

Your Matomo account is protected by a password. Normally that is exactly what you want. But there is a problem: your dashboard needs to fetch data on its own, hundreds of times a day, and nobody is sitting there typing your password each time.

An API key (in Matomo it is officially called an auth token) is a long random string of letters and numbers, something like a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6. It acts like a password for software. When your dashboard asks Matomo for data, it presents this token, and Matomo trusts it just like a logged-in user.

Three important things about a token:

• It is created inside your Matomo account. Only you (or someone you invite to your Matomo) can make one, which is why we have to ask you for it.
• It is secret. Anyone with the token can read your analytics data just like a logged-in user can. Treat it like your banking password, not like your wifi password.
• It can be discarded and replaced without disturbing anything else. If a token ever gets lost or exposed, you simply create a new one and the old one stops mattering. Your main login is safe.

That last point is why API keys exist as a separate thing from your main password. They can be issued per purpose and deleted individually.

What you need before you start

You will need just two things:

• The web address (URL) of your Matomo login page. For a Matomo cloud subscription it looks like https://yourname.matomo.cloud. For a self-hosted installation it is whatever address your Matomo was installed on. If you are unsure, check your Matomo welcome email or ask us.
• Your Matomo username/email and password.

You do not need any special software. Everything happens in your normal web browser.

Step-by-step: creating your Matomo auth token

Here is every click, in order. These steps are for Matomo version 5 and newer, which is what current installations run.

Step 1: Log in to your Matomo dashboard

Open your browser, go to your Matomo web address, and log in as usual with your email/username and password. You will land on your dashboard, the screen with graphs and tables showing your website traffic.

Step 2: Open the Administration area

Look at the very top right of the page. You will see a small row of icons, often with your name or avatar at the end. Click the cog/gear icon (Administration). This opens the settings area.

Step 3: Go to Personal → Security

On the left of the settings screen is a menu. Find the Personal section and click Security. This page lists the tokens already created for your account (it may say you have none yet, which is fine) and has a button to create a new one.

Step 4: Click Create new token

On the Security page, click the + Create new token button. Matomo will ask you to confirm your account password. Type it in and continue. This is just Matomo double-checking it is really you.

Step 5: Describe the token

You will see Create new token options. In the description field, type what this token is for, e.g. Xenium Designs Dashboard. This does not affect anything technically; it is just a label that will remind you later what this token is connected to. This is worth being tidy about: if you ever have several tokens, the descriptions are how you tell them apart.

Step 6: Leave Expire date blank

The next option asks if you want the token to stop working at some future date. Leave it empty. Choosing a date means the token will stop working when that date passes, and the dashboard data will go stale until you create and share a new one. The default (no date, never expires) is the right choice here.

Step 7: The Only allow secure requests checkbox

You may see a checkbox called Only allow secure requests. Leave it unticked. Our dashboard connection uses standard GET requests, and tokens with this option enabled are rejected for those requests. If a developer ever asks you to enable it, that means they are sending the token via POST requests instead. For our dashboard, off is correct.

Step 8: Click Create new token

Click the Create new token button to finish.

Step 9: Save the token somewhere safe

You will now see your token, the long random string. This is the only time Matomo ever shows it to you. After this screen, Matomo hides it forever; you cannot come back later to look at it again.

So copy it now: click it (or highlight the text) and copy it to your clipboard, then paste it somewhere safe. The two best places are a password manager (Bitwarden, 1Password, etc.) or, failing that, a plain text file only you keep. Then send it to us securely, or paste it wherever we have asked you to send it.

Step-by-step in short form

For reference, once you are familiar, here is the same walk compressed into numbered form:

1. Log in to Matomo.
2. Go to: Administration (cog icon in the top right) → Personal → Security.
3. Click: Create new token.
4. Confirm your password.
5. Enter a short description, e.g. Xenium Designs Dashboard.
6. Leave Expire date empty.
7. Leave Only allow secure requests off unless told otherwise.
8. Click: Create new token.
9. Copy the token immediately into a password manager (it is only shown once) and send it to us.

Troubleshooting

"I do not see Administration or Personal"

You may be logged in with an account that only has "view" rights, not admin rights. Ask whoever manages your Matomo (often us or your IT person) to either raise your rights or create the token under an account that can.

"I do not appear to have any tokens, and I cannot create one"

This is almost always the same rights issue as above. Only users with admin (or at least write) rights can create tokens for their own accounts. Check which user account you logged in with; it may not be your main admin account.

"I created a token but the dashboard is not picking up data"

The three usual causes are: a stray space before or after the token when it was copied, the "Only allow secure requests" option was left on when it should be off, or an expire date was set and the token has since run out. Delete the token, create a fresh one from scratch, and double-check all three points.

"I think my token got exposed somewhere"

Do not panic, this is recoverable in about a minute. On the same Personal → Security page, find the token in your list, delete it, create a replacement following the steps above, and give the new token to us. Any tool still holding the old token instantly loses access the moment it is deleted. Your password and your analytics data are untouched.

What we do with your token

Once we have your token, it is stored server-side in the configuration of your dashboard, where only our scheduled data-fetching script can reach it. That script quietly asks your Matomo for your numbers and files them into your dashboard's database, so every chart you see is up to date. You will never see the token used anywhere, and we will never display it or paste it into any file you might later share.

Why this matters

That token becomes the bridge that lets your dashboard stay current without anyone logging in, copying, or pasting anything. Setup takes two minutes, and this is the only step on your side of the process.

Frequently asked questions