How do OAuth 2.0 tokens work in Matomo?

OAuth 2.0 tokens authenticate API requests in Matomo. Each token can be defined with a specific scope and lifetime, which controls what data it can access and how long it remains valid.

OAuth 2.0 token behaviour and permissions

These frequently asked questions explain how OAuth 2.0 tokens work in Matomo, including scopes, permissions, and how access is controlled.

1. Can multiple scopes be requested in a single token?
   No. Only a single scope can be requested per token.

2. Can OAuth tokens access all Matomo APIs?
   Access depends on the granted scope. Even if the authenticated user is a superuser, the token is limited to the approved scope.

3. Are OAuth tokens tied to a user?
   Yes. Tokens represent access granted by a user (typically a superuser during setup) and inherit permissions based on both the user and the approved scope.

Technical integration and implementation

These questions cover how to implement OAuth 2.0 in Matomo, including API usage, endpoints, and authentication flows.

1. Can OAuth 2.0 be used with all Matomo APIs?
   Yes. OAuth 2.0 tokens can be used with standard Matomo API endpoints by replacing token_auth with a Bearer token.

2. Are there alternative (clean) OAuth endpoints?
   Yes. In addition to query-based endpoints, cleaner routes such as /oauth2/authorize and /oauth2/token may be available depending on configuration.

3. Is PKCE required?
   PKCE is required for public clients and recommended for improved security.

4. Can I use OAuth 2.0 without user interaction?
   Yes. Use the Client Credentials flow for server-to-server integrations.

5. Do users need to manually handle access tokens?
   No. Tokens are issued to the client application and used programmatically. Users do not manually copy or manage tokens.

Learn more about the difference between OAuth 2.0 and token_auth in Matomo.