Updates docs

AltamashShaikh · AltamashShaikh · commit 0ded9a3fb699 · 2026-04-10T08:20:59.000+05:30
diff --git a/.gitignore b/.gitignore
@@ -12,4 +12,5 @@
 /docs/changelog.md
 /docs/changelog-*.md
 /docs/cache/
-/docs/*/cache/
+/docs/*/cache/
+.codex
diff --git a/docs/5.x/authentication-in-depth.md b/docs/5.x/authentication-in-depth.md
@@ -9,7 +9,7 @@ There are different ways a user can authenticate in Matomo:
 * Using username / password and the regular login form. 
 * The [logme](https://matomo.org/faq/how-to/faq_30/) feature can be used to log someone in using username and password in the URL. 
 * Using a `token_auth` URL parameter for our HTTP API's and widgets.
-* Using OAuth2 bearer tokens for external applications when the OAuth2 plugin is installed.
+* Using OAuth 2.0 bearer tokens for external applications when the OAuth 2.0 plugin is installed.
 
 ## Username and password login
 
@@ -65,13 +65,13 @@ When there is a request and we can use a session, then Matomo [checks first if t
 * When a `token_auth` parameter is set by us, then we usually POST the token_auth. This is for security reasons so the token_auth won't appear in server logs. Otherwise a sysadmin could see the token in the logs and do all sort of actions on behalf of another user.
 * Remember that users should not share the token_auth as it is the same as them sharing their username/password.
 
-## OAuth2
+## OAuth 2.0
 
-If the [OAuth2](/guides/oauth2) plugin is installed, external applications can authenticate against Matomo using OAuth2 access tokens.
+If the [OAuth 2.0](/guides/oauth2) plugin is installed, external applications can authenticate against Matomo using OAuth 2.0 access tokens.
 
-This is mainly useful when integrating third-party or custom applications that should not receive a long-lived `token_auth`. In that case the application first obtains an access token through the plugin's OAuth2 endpoints and then sends that token as a bearer token when calling supported Matomo APIs.
+This is mainly useful when integrating third-party or custom applications that should not receive a long-lived `token_auth`. In that case the application first obtains an access token through the plugin's OAuth 2.0 endpoints and then sends that token as a bearer token when calling supported Matomo APIs.
 
-Depending on the application type, you would typically use either the Authorization Code flow with PKCE or the Client Credentials flow. For the integration flow and request examples, see the [OAuth2 guides](/guides/oauth2).
+Depending on the application type, you would typically use either the Authorization Code flow with PKCE or the Client Credentials flow. For the integration flow and request examples, see the [OAuth 2.0 guides](/guides/oauth2).
 
 ## Alternative login plugins
 
diff --git a/docs/5.x/oauth2.md b/docs/5.x/oauth2.md
@@ -7,12 +7,14 @@ subGuides:
   - oauth2/api-usage
   - oauth2/faq
 ---
-# OAuth2
+# OAuth 2.0
 
-This section contains guides that will help you authenticate external applications against Matomo using OAuth2.
+This section contains guides that will help you authenticate external applications against Matomo using OAuth 2.0.
 
-**OAuth2** is a plugin for Matomo that adds a first-party OAuth2 Authorization Server. It allows external applications to access Matomo APIs using OAuth2 access tokens instead of sending a `token_auth`.
+The **OAuth 2.0** plugin adds a first-party OAuth 2.0 Authorization Server to Matomo. It allows external applications to access Matomo APIs using OAuth 2.0 access tokens instead of sending a `token_auth`.
 
-The plugin supports the **Authorization Code** flow with **PKCE**, **Client Credentials**, and **Refresh Token** support. OAuth clients can be managed in Matomo under **Administration => Platform => OAuth2**. In Matomo Cloud, this screen is available under **Administration => Export => OAuth2**.
+The plugin supports the **Authorization Code** flow with **PKCE**, **Client Credentials**, and **Refresh Token** support. Applications authenticate with bearer tokens and can be limited to the scopes granted to each OAuth client.
+
+OAuth 2.0 clients can be managed in Matomo under **Administration => Platform => OAuth 2.0**. In Matomo Cloud, this screen is available under **Administration => Export => OAuth 2.0**. From there you can create, edit, pause, resume, or delete clients, and rotate secrets for confidential clients.
 
 If you are looking for general API authentication details, also see [Authentication In Depth](/guides/authentication-in-depth) and [Querying the Reporting API](/guides/querying-the-reporting-api).
diff --git a/docs/5.x/oauth2/api-usage.md b/docs/5.x/oauth2/api-usage.md
@@ -1,8 +1,8 @@
 ---
 category: Integrate
-title: OAuth2 API Usage
+title: OAuth 2.0 API Usage
 ---
-# Calling Matomo APIs with OAuth2
+# Calling Matomo APIs with OAuth 2.0
 
 Once your application has obtained an access token, it can call Matomo APIs using the `Authorization` header.
 
@@ -23,16 +23,16 @@ curl 'https://matomo.example.com/index.php' \
   -d 'format=json'
 ```
 
-## OAuth2 compared to `token_auth`
+## OAuth 2.0 compared to `token_auth`
 
 By default, many Matomo API guides use `token_auth` examples because `token_auth` is available in every Matomo installation.
 
-When the OAuth2 plugin is installed, external applications can use OAuth2 bearer tokens instead. This avoids sharing a long-lived auth token with the external application and lets you choose a grant type that matches the integration.
+When the OAuth 2.0 plugin is installed, external applications can use OAuth 2.0 bearer tokens instead. This avoids sharing a long-lived auth token with the external application, lets you choose a grant type that matches the integration, and makes it easier to limit and revoke access without affecting other applications.
 
 If you are integrating a backend service with no user interaction, the Client Credentials flow is usually the best fit. If your application acts on behalf of a user, use the Authorization Code flow.
 
 ## Notes
 
 * Use HTTPS whenever you send access tokens.
 * The plugin currently allows only one scope per request.
-* Keep using the standard `token_auth` flow in integrations where the OAuth2 plugin is not installed.
+* Keep using the standard `token_auth` flow in integrations where the OAuth 2.0 plugin is not installed.
diff --git a/docs/5.x/oauth2/authorization-code.md b/docs/5.x/oauth2/authorization-code.md
@@ -1,8 +1,8 @@
 ---
 category: Integrate
-title: OAuth2 Authorization Code Flow
+title: OAuth 2.0 Authorization Code Flow
 ---
-# OAuth2 Authorization Code Flow
+# OAuth 2.0 Authorization Code Flow
 
 Use the Authorization Code flow when your application acts on behalf of a Matomo user.
 
@@ -11,7 +11,7 @@ Use the Authorization Code flow when your application acts on behalf of a Matomo
 The Authorization Code flow works like this:
 
 1. Your application redirects the user to the Matomo authorization endpoint.
-2. The user logs in and approves access.
+2. The user logs in, reviews the requested permissions, and approves access.
 3. Matomo redirects back with an authorization `code`.
 4. Your application exchanges the code for an access token.
 5. Your application calls Matomo APIs using `Authorization: Bearer ACCESS_TOKEN`.
@@ -59,7 +59,13 @@ https://matomo.example.com/index.php?module=OAuth2&action=authorize
 &state=abc123
 ```
 
-After the user approves access, Matomo redirects back to your application:
+The user will:
+
+1. Log in to Matomo.
+2. Review the requested permissions.
+3. Click **Allow**.
+
+After approval, Matomo redirects back to your application:
 
 ```text
 https://example-app.com/oauth/callback?code=AUTHORIZATION_CODE&state=abc123
@@ -106,6 +112,8 @@ curl -X POST 'https://matomo.example.com/index.php?module=OAuth2&action=token' \
 
 ## Refresh an access token
 
+Use a refresh token to obtain a new access token.
+
 ### Public client
 
 ```bash
@@ -129,4 +137,4 @@ curl -X POST 'https://matomo.example.com/index.php?module=OAuth2&action=token' \
 
 ## What to read next
 
-Once you have an access token, see [Calling Matomo APIs with OAuth2](/guides/oauth2/api-usage).
+Once you have an access token, see [Calling Matomo APIs with OAuth 2.0](/guides/oauth2/api-usage).
diff --git a/docs/5.x/oauth2/client-credentials.md b/docs/5.x/oauth2/client-credentials.md
@@ -1,15 +1,15 @@
 ---
 category: Integrate
-title: OAuth2 Client Credentials Flow
+title: OAuth 2.0 Client Credentials Flow
 ---
-# OAuth2 Client Credentials Flow
+# OAuth 2.0 Client Credentials Flow
 
 Use the Client Credentials flow when a backend service needs to access Matomo APIs without user interaction.
 
 Typical examples include:
 
 * Internal analytics dashboards
-* Scheduled exports
+* Scheduled data exports
 * Backend integrations
 
 ## Request an access token
@@ -37,6 +37,6 @@ Depending on your client configuration, a refresh token may also be available th
 
 ## When to use this flow
 
-Use this flow only for trusted server-side applications that can keep credentials secret.
+Use this flow for trusted server-side applications that need server-to-server access and can keep credentials secret.
 
 If the application needs a user to log in and approve access, use the [Authorization Code flow](/guides/oauth2/authorization-code) instead.
diff --git a/docs/5.x/oauth2/faq.md b/docs/5.x/oauth2/faq.md
@@ -1,8 +1,8 @@
 ---
 category: Integrate
-title: OAuth2 Developer FAQ
+title: OAuth 2.0 Developer FAQ
 ---
-# OAuth2 Developer FAQ
+# OAuth 2.0 Developer FAQ
 
 ## Which grant types are supported?
 
@@ -54,6 +54,14 @@ Optional cleaner routes can also be configured:
 * `/oauth2/authorize`
 * `/oauth2/token`
 
+## When is a client secret shown?
+
+For confidential clients, the client secret is shown in full only when the client is created or when the secret is rotated. After that, the secret is masked in the UI.
+
+## Can I rotate a client secret?
+
+Yes. Confidential clients support secret rotation from the edit screen. Rotate the secret if you need a new value or if the existing one may have been exposed.
+
 ## Can I still use `token_auth`?
 
-Yes. The OAuth2 plugin adds an alternative authentication method for external applications. Existing `token_auth` based integrations continue to be relevant for Matomo installations where the plugin is not enabled.
+Yes. The OAuth 2.0 plugin adds an alternative authentication method for external applications. Existing `token_auth` based integrations continue to be relevant for Matomo installations where the plugin is not enabled.
diff --git a/docs/5.x/oauth2/setup.md b/docs/5.x/oauth2/setup.md
@@ -1,14 +1,14 @@
 ---
 category: Integrate
-title: OAuth2 Setup
+title: OAuth 2.0 Setup
 ---
-# Setting up OAuth2
+# Setting up OAuth 2.0
 
 In this guide you will learn how to configure an OAuth client so an external application can request access tokens for Matomo.
 
-## What the OAuth2 plugin provides
+## What the OAuth 2.0 plugin provides
 
-The plugin adds a first-party OAuth2 Authorization Server to Matomo. Once enabled, applications can authenticate against Matomo using bearer tokens instead of sharing a permanent `token_auth`.
+The plugin adds a first-party OAuth 2.0 Authorization Server to Matomo. Once enabled, applications can authenticate against Matomo using bearer tokens instead of sharing a permanent `token_auth`.
 
 The plugin supports these grant types:
 
@@ -25,9 +25,11 @@ The plugin currently supports these scopes:
 
 See the [permissions guide](/guides/permissions) for more information.
 
-## OAuth endpoints
+Access tokens are sent as bearer tokens when calling Matomo APIs. The plugin uses RSA keys to sign JWT access tokens.
 
-Matomo exposes these OAuth2 endpoints:
+## OAuth 2.0 endpoints
+
+Matomo exposes these OAuth 2.0 endpoints:
 
 | Endpoint | Description |
 |--------|-------------|
@@ -57,11 +59,15 @@ Create a client and configure:
 * The allowed scopes
 * The redirect URI for the Authorization Code flow
 
+From the client list, you can pause or resume a client, open it for editing, or delete it. For confidential clients, secret rotation is available from the edit screen.
+
 You can create either of these client types:
 
 * **Confidential** clients, which use a client secret
 * **Public** clients, which do not use a client secret and should use PKCE
 
+Client secrets are shown in full only when a confidential client is created or when its secret is rotated. After that, the secret is masked and you need to rotate it again if you want a new value.
+
 Example client:
 
 ```text
@@ -76,6 +82,8 @@ Use a **public** client when your application cannot safely store a client secre
 
 Use a **confidential** client when your application runs on a trusted backend and can safely keep the client secret private.
 
+At the time of writing, the plugin allows only one scope per request and the requested scope needs to match the client configuration.
+
 ## What to read next
 
 Once your client is configured, continue with the [Authorization Code guide](/guides/oauth2/authorization-code) or the [Client Credentials guide](/guides/oauth2/client-credentials).
diff --git a/docs/5.x/querying-the-reporting-api.md b/docs/5.x/querying-the-reporting-api.md
@@ -17,7 +17,7 @@ If you want to request data in any language (PHP, Python, Ruby, ASP, C++, Java,
 If the API call requires the token_auth and the HTTP request is sent over untrusted networks, we highly advise that you use an encrypted request. Otherwise, your token\_auth is exposed to eavesdroppers. This can be done by using https instead of http.
 </div>
 
-If the [OAuth2](/guides/oauth2) plugin is installed, external applications can also authenticate using OAuth2 bearer tokens instead of sending a `token_auth`. The examples below continue to use `token_auth` because it is available in every Matomo installation.
+If the [OAuth 2.0](/guides/oauth2) plugin is installed, external applications can also authenticate using OAuth 2.0 bearer tokens instead of sending a `token_auth`. The examples below continue to use `token_auth` because it is available in every Matomo installation.
 
 You can, for example, get the list of countries where most of your visitors in the current month are from. Here is an example in PHP:
 
