Using API tokens with LDAP or SAML authentication
When LDAP or SAML authentication is enabled, users log in to Matomo through an external identity system. API access works differently.
When an application, script, or integration connects to the Matomo API, Matomo uses an API token (token_auth) to authenticate the request. The API tokens are a separate authentication mechanism for API requests and are generated, stored, and managed within Matomo.
How API tokens work with LDAP or SAML
When LDAP or SAML authentication is enabled:
- Users sign in through their LDAP directory or SAML Identity Provider.
- API tokens continue to be generated, stored, and managed within Matomo.
- API requests continue to authenticate using
token_auth.
API tokens are linked to Matomo user accounts and inherit the permissions assigned to that account.
Once an API token has been created, it can be used to authenticate API requests regardless of whether the user normally signs in through LDAP, SAML, or a local Matomo account.
Password confirmation
Some token management actions require additional identity verification before they can be completed. When generating or managing an API token, Matomo may ask you to confirm your password before performing the action.
For users authenticated through LDAP or SAML, the required authentication method depends on how the account was created and configured:
- Account created through SAML Just-In-Time (JIT) provisioning, you may not have a local Matomo password. From LoginSAML 5.5.0, you can reauthenticate through your SAML Identity Provider when password confirmation is required.
- Account authenticates through LDAP, your password is typically managed by the LDAP directory.
If password confirmation fails or a local password is required, contact your Matomo superuser. They can review your account configuration and, if appropriate, configure or reset a local Matomo password.
How fallback login works
Some users may encounter situations where access to the standard Matomo login form is required, such as troubleshooting authentication issues, recovering administrative access, or using accounts with Matomo credentials.
In SAML environments, users are often redirected to their SAML Identity Provider (IdP) when signing in. In these situations, users need to login with the standard Matomo username and password form.
This is commonly known as fallback login and is accessed by appending the ?normal parameter to the Matomo login URL, for example:
https://your-matomo.example.com/index.php?module=Login&action=login&normal
The exact behaviour depends on how SAML authentication is configured and whether the user has local Matomo credentials available. Learn more about what happens with normal login when LDAP or SAML enabled?
Recommended for API integrations
Before creating API tokens for integrations or automation, consider how the account will be managed over time. The recommendations below can help reduce disruption when authentication settings change or tokens need to be rotated.
1. Use a dedicated service account
A dedicated service account is a Matomo user account created specifically for an integration, application, or automated process rather than an individual person.
Common examples include data exports, integration with reporting tools (Power BI, Tableau, Looker Studio), data warehouse integrations and third-party integrations.
In these scenarios, API access should continue working even if individual employees change roles, leave the organisation, or have their LDAP or SAML access removed. Refer to the guide on adding a local user account.
2. LDAP synchronisation requirements (if applicable)
Before an LDAP user can manage API tokens, the user must exist in Matomo. If an LDAP user cannot generate a token, verify that:
☐ The user exists in Matomo.
☐ LDAP synchronisation completed successfully.
☐ The user has logged in at least once (if automatic provisioning is enabled).
If the user does not exist in Matomo, synchronise or provision the account before generating API tokens.
3. Removing an LDAP or SAML user
Removing a user from LDAP or SAML does not automatically guarantee that associated Matomo API tokens are revoked. When offboarding a user:
☐ Check whether the user still exists in Matomo.
☐ Revoke any active API tokens.
☐ Disable or remove the Matomo account if no longer required.
☐ Review integrations that may be using the user’s tokens.
☐ Verify that no automation or reporting tools depend on the account.
For long-term integrations, avoid using personal LDAP or SAML accounts. Regular reviews of user and service accounts, and API tokens can help identify unused or orphaned credentials.
4. API token security best practices
Treat API tokens as sensitive credentials as they provide the same level of access as the Matomo user account that created them.
| ✓ Do | ✗ Don’t |
|---|---|
| Use dedicated service accounts for integrations. | Use personal account API tokens for long-running integrations. |
| Grant only the permissions required. | Use Superuser tokens unless absolutely necessary. |
| Store tokens securely in secret managers, environment variables, or encrypted credential stores. | Store tokens in source code, documentation, emails, or chat messages. |
| Use POST requests or HTTP headers where supported. | Include token_auth values in URLs whenever possible. |
| Review and rotate tokens regularly. | Leave unused or orphaned tokens active indefinitely. |
Troubleshooting FAQ
I use SAML and cannot confirm my password to create a token
If your account was created through SAML Just-In-Time (JIT) provisioning, you may not have a local Matomo password.
From LoginSAML 5.5.0, you can reauthenticate through your SAML Identity Provider when password confirmation is required. If password confirmation fails or a local password is required, contact your Matomo superuser.
My LDAP user cannot generate a token
You will need to verify that the user exists in Matomo and LDAP synchronisation has completed successfully. The user should have logged in at least once (if automatic provisioning is used) and they have permissions to manage personal API tokens.
Should my API integration use a local user or an LDAP/SAML user?
For most integrations, a dedicated Matomo service account is recommended. This provides stable credentials, simplifies token management, and reduces the risk of disruptions caused by employee offboarding or identity system changes.
Does disabling a user in LDAP or SAML revoke Matomo API tokens?
Disabling a user in LDAP or SAML does not automatically guarantee that associated Matomo API tokens are revoked. Review the user’s Matomo account and revoke any active tokens as part of your offboarding process.
Can I use local login when LDAP or SAML authentication is enabled?
Yes, only if the account has local Matomo credentials and local login is permitted by your authentication configuration.
In SAML environments, the standard Matomo login form can typically be accessed using the ?normal parameter. LDAP users generally continue using the standard login form directly.