Merge pull request #20 from matomo-org/fix-readme

Fixes README to display correctly

Author: AltamashShaikh

CHANGELOG.md

@@ -1,3 +1,5 @@
-5.0.0 - 2026-04-13
+5.0.1 - 2026-04-17
+- Fixes README.md
 
-Initial release to create OAuth 2.0 clients for token generation and API access
+5.0.0 - 2026-04-13
+- Initial release to create OAuth 2.0 clients for token generation and API access

README.md

@@ -1,22 +1,20 @@
 # OAuth 2.0 Plugin for Matomo
 
-This plugin adds a **first-party OAuth 2.0 Authorization Server** to Matomo, allowing external applications to securely access Matomo APIs using OAuth2 access tokens instead of `token_auth`.
-
-It supports standard OAuth 2.0 flows including **Authorization Code (PKCE)**, **Client Credentials**, and **Refresh Token**.
-
 [![Build Status](https://github.com/matomo-org/plugin-OAuth2/actions/workflows/matomo-tests.yml/badge.svg)](https://github.com/matomo-org/plugin-OAuth2/actions/workflows/matomo-tests.yml)
 
 ## Description
 
+This plugin adds a **first-party OAuth 2.0 Authorization Server** to Matomo, allowing external applications to securely access Matomo APIs using OAuth2 access tokens instead of `token_auth`.
+
+It supports standard OAuth 2.0 flows including **Authorization Code (PKCE)**, **Client Credentials**, and **Refresh Token**.
+
 The OAuth 2.0 plugin replaces static authentication with a token-based flow tied to your existing login system. Each application requests permission, receives scoped access, and operates within defined limits. No need to distribute or manage long-lived credentials across tools and services.
 
 Tokens expire by default, can be refreshed when needed, and revoked instantly without affecting other integrations. This reduces exposure and simplifies access management.
 
 For teams running multiple integrations, OAuth 2.0 is the practical choice for secure, maintainable access to Matomo data. Every connection is authorised, bounded, and straightforward to control.
 
----
-
-# Features
+## Features
 
 - OAuth 2.0 Authorization Server integrated with Matomo
 - Manage OAuth clients via **Administration → Platform → OAuth 2.0** (For Matomo Cloud it will be **Administration → Export → OAuth 2.0**)
@@ -34,12 +32,10 @@ For teams running multiple integrations, OAuth 2.0 is the practical choice for s
 - Bearer token authentication for Matomo APIs
 - Client management UI with create, edit, pause/resume, delete, and secret rotation for confidential clients
 
----
-
-# OAuth Endpoints
+## OAuth Endpoints
 
 | Endpoint | Description |
-|--------|-------------|
+| --- | --- |
 | `/index.php?module=OAuth2&action=authorize` | Authorization endpoint |
 | `/index.php?module=OAuth2&action=token` | Token endpoint |
 
@@ -50,11 +46,9 @@ Optional cleaner routes can be added:
 /oauth2/token
 ```
 
----
+## Setup
 
-# Setup
-
-## 1. Create an OAuth Client
+### 1. Create an OAuth Client
 
 Navigate to:
 
@@ -84,9 +78,7 @@ Client Secret: 7fa9c0f81b8b4a12
 Redirect URI: https://example-app.com/oauth/callback
 ```
 
----
-
-# OAuth Flow Overview
+## OAuth Flow Overview
 
 1. Client redirects the user to `/authorize`
 2. User logs into Matomo and approves access
@@ -98,11 +90,9 @@ Redirect URI: https://example-app.com/oauth/callback
 Authorization: Bearer ACCESS_TOKEN
 ```
 
----
-
-# Authorization Code Flow
+## Authorization Code Flow
 
-## Step 1 — Generate PKCE parameters (Public Clients)
+### Step 1: Generate PKCE Parameters (Public Clients)
 
 PKCE requires two values:
 
@@ -122,11 +112,9 @@ Where:
 code_challenge = BASE64URL(SHA256(code_verifier))
 ```
 
----
+### Step 2: Redirect User to Authorization Endpoint
 
-## Step 2 — Redirect user to Authorization Endpoint
-
-### PKCE Example (Public Client)
+#### PKCE Example (Public Client)
 
 ```
 https://matomo.example.com/index.php?module=OAuth2&action=authorize
@@ -139,7 +127,7 @@ https://matomo.example.com/index.php?module=OAuth2&action=authorize
 &code_challenge_method=S256
 ```
 
-### Confidential Client Example
+#### Confidential Client Example
 
 ```
 https://matomo.example.com/index.php?module=OAuth2&action=authorize
@@ -162,13 +150,11 @@ Matomo will redirect back:
 https://example-app.com/oauth/callback?code=AUTHORIZATION_CODE&state=abc123
 ```
 
----
-
-# Exchange Authorization Code for Tokens
+## Exchange Authorization Code for Tokens
 
 **Note:** The scope should be same as client scope and only one scope is allowed at the moment.
 
-## PKCE Token Request
+### PKCE Token Request
 
 ```
 curl -X POST 'https://matomo.example.com/index.php?module=OAuth2&action=token' \
@@ -180,7 +166,7 @@ curl -X POST 'https://matomo.example.com/index.php?module=OAuth2&action=token' \
   -d 'code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk'
 ```
 
-## Confidential Client Token Request
+### Confidential Client Token Request
 
 ```
 curl -X POST 'https://matomo.example.com/index.php?module=OAuth2&action=token' \
@@ -192,9 +178,7 @@ curl -X POST 'https://matomo.example.com/index.php?module=OAuth2&action=token' \
   -d 'code=AUTHORIZATION_CODE'
 ```
 
----
-
-# Client Credentials Flow (Server-to-Server)
+## Client Credentials Flow (Server-to-Server)
 
 The **Client Credentials grant** is used when a backend service needs to access Matomo APIs **without user interaction**.
 
@@ -204,7 +188,7 @@ Typical use cases:
 - Scheduled data exports
 - Backend integrations
 
-## Token Request
+### Token Request
 
 ```
 curl -X POST 'https://matomo.example.com/index.php?module=OAuth2&action=token' \
@@ -215,9 +199,7 @@ curl -X POST 'https://matomo.example.com/index.php?module=OAuth2&action=token' \
   -d 'scope=matomo:read'
 ```
 
----
-
-# Example Token Response
+## Example Token Response
 
 ```json
 {
@@ -228,9 +210,7 @@ curl -X POST 'https://matomo.example.com/index.php?module=OAuth2&action=token' \
 }
 ```
 
----
-
-# Refresh Token
+## Refresh Token
 
 Use a refresh token to obtain a new access token.
 
@@ -255,9 +235,7 @@ curl -X POST 'https://matomo.example.com/index.php?module=OAuth2&action=token' \
   -d 'refresh_token=def50200a1b9'
 ```
 
----
-
-# Calling Matomo APIs with OAuth 2.0
+## Calling Matomo APIs with OAuth 2.0
 
 Once an access token is obtained, call Matomo APIs using the **Bearer token**.
 
@@ -283,9 +261,7 @@ Example response:
 }
 ```
 
----
-
-# Security Notes
+## Security Notes
 
 - Never expose **client secrets** in frontend applications.
 - Public clients **must use PKCE**.

docs/index.md

@@ -0,0 +1,3 @@
+## Documentation
+
+The [OAuth 2.0 User Guide](https://matomo.org/faq/how-to/set-up-oauth-2-0-authentication-for-the-matomo-api/) and the [README.md](https://github.com/matomo-org/plugin-OAuth2/blob/5.x-dev/README.md#features) cover how to get the most out of this plugin.

plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "OAuth2",
   "description": "Provide secure access to the Matomo API using scoped permissions. No static credentials.",
-  "version": "5.0.0",
+  "version": "5.0.1",
   "theme": false,
   "require": {
     "php": ">=8.1.0",