Matomo OAuth2 API

{"openapi":"3.1.0","info":{"title":"Matomo Reporting API for OAuth2 plugin","version":"1.0.0"},"servers":[{"url":"https:\/\/demo-proxy.innocraft.cloud\/","description":"Current Matomo instance"}],"paths":{"\/index.php?module=API&method=OAuth2.getClients":{"get":{"tags":["OAuth2"],"description":"Lists all OAuth2 clients configured in Matomo (super users only).","operationId":"OAuth2.getClients","parameters":[{"$ref":"#\/components\/parameters\/formatOptional"}],"responses":{"200":{"description":"OAuth2 clients ordered by most recently updated first.\n\nExample responses require Super User access. Use Try it out to see a live response."},"400":{"$ref":"#\/components\/responses\/BadRequest"},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"},"500":{"$ref":"#\/components\/responses\/ServerError"},"default":{"$ref":"#\/components\/responses\/DefaultError"}}}},"\/index.php?module=API&method=OAuth2.getClient":{"get":{"tags":["OAuth2"],"description":"Returns one OAuth2 client configured in Matomo (super users only).","operationId":"OAuth2.getClient","parameters":[{"$ref":"#\/components\/parameters\/formatOptional"},{"name":"clientId","in":"query","description":"32-character hexadecimal client identifier.","required":true,"schema":{"type":"string","example":"0123456789abcdef0123456789abcdef"}}],"responses":{"200":{"description":"Sanitized OAuth2 client details for the requested client.\n\nExample responses require Super User access. Use Try it out to see a live response."},"400":{"$ref":"#\/components\/responses\/BadRequest"},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"},"500":{"$ref":"#\/components\/responses\/ServerError"},"default":{"$ref":"#\/components\/responses\/DefaultError"}}}},"\/index.php?module=API&method=OAuth2.getScopes":{"get":{"tags":["OAuth2"],"description":"Returns the OAuth2 scopes enabled for client configuration (super users only).","operationId":"OAuth2.getScopes","parameters":[{"$ref":"#\/components\/parameters\/formatOptional"}],"responses":{"200":{"description":"Enabled scope identifiers mapped to their translated descriptions.\n\nExample responses require Super User access. Use Try it out to see a live response."},"400":{"$ref":"#\/components\/responses\/BadRequest"},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"},"500":{"$ref":"#\/components\/responses\/ServerError"},"default":{"$ref":"#\/components\/responses\/DefaultError"}}}},"\/index.php?module=API&method=OAuth2.createClient":{"get":{"tags":["OAuth2"],"description":"Creates a new OAuth2 client and optionally returns the generated secret.","operationId":"OAuth2.createClient","parameters":[{"$ref":"#\/components\/parameters\/formatOptional"},{"name":"name","in":"query","description":"Display name shown in the Matomo UI.","required":true,"schema":{"type":"string","example":"Pricing"}},{"name":"grantTypes","in":"query","description":"Grant types to enable (`authorization_code`, `client_credentials`, `refresh_token`).","required":true,"schema":{"type":"array","items":{"type":"string"},"example":["authorization_code"]}},{"name":"scope","in":"query","description":"Single scope identifier to allow for the client. Must match one of the enabled OAuth2 scopes.","required":true,"schema":{"type":"string","example":"matomo:read"}},{"name":"redirectUris","in":"query","description":"Allowed redirect URIs (array or newline-separated string).","required":false,"schema":{"oneOf":[{"type":"string","default":"[]"},{"type":"array","items":{"type":"string"},"default":[]}]}},{"name":"description","in":"query","description":"Optional description for administrators.","required":false,"schema":{"type":"string","default":""}},{"name":"type","in":"query","description":"`confidential` (default, requires secret) or `public` (no client secret).","required":false,"schema":{"type":"string","default":"confidential"}},{"name":"active","in":"query","description":"`'1'` to enable the client or `'0'` to disable it.","required":false,"schema":{"type":"string","default":"1"}},{"name":"passwordConfirmation","in":"query","description":"Current user's password confirmation.","required":false,"schema":{"type":"string","default":""}}],"responses":{"200":{"description":"The sanitized client record and the generated plaintext secret when the created client is confidential.\n\nExample responses require Super User access. Use Try it out to see a live response."},"400":{"$ref":"#\/components\/responses\/BadRequest"},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"},"500":{"$ref":"#\/components\/responses\/ServerError"},"default":{"$ref":"#\/components\/responses\/DefaultError"}}}},"\/index.php?module=API&method=OAuth2.updateClient":{"get":{"tags":["OAuth2"],"description":"Updates an OAuth2 client and optionally returns a newly generated secret.","operationId":"OAuth2.updateClient","parameters":[{"$ref":"#\/components\/parameters\/formatOptional"},{"name":"clientId","in":"query","description":"32-character hexadecimal client identifier.","required":true,"schema":{"type":"string","example":"0123456789abcdef0123456789abcdef"}},{"name":"name","in":"query","description":"Display name shown in the Matomo UI.","required":true,"schema":{"type":"string","example":"Pricing"}},{"name":"grantTypes","in":"query","description":"Grant types to enable (`authorization_code`, `client_credentials`, `refresh_token`).","required":true,"schema":{"type":"array","items":{"type":"string"},"example":["authorization_code"]}},{"name":"scope","in":"query","description":"Single scope identifier to allow for the client. Must match one of the enabled OAuth2 scopes.","required":true,"schema":{"type":"string","example":"matomo:read"}},{"name":"redirectUris","in":"query","description":"Allowed redirect URIs (array or newline-separated string).","required":false,"schema":{"oneOf":[{"type":"string","default":"[]"},{"type":"array","items":{"type":"string"},"default":[]}]}},{"name":"description","in":"query","description":"Optional description for administrators.","required":false,"schema":{"type":"string","default":""}},{"name":"type","in":"query","description":"`confidential` (default, requires secret) or `public` (no client secret).","required":false,"schema":{"type":"string","default":"confidential"}},{"name":"active","in":"query","description":"`'1'` to enable the client or `'0'` to disable it.","required":false,"schema":{"type":"string","default":"1"}},{"name":"passwordConfirmation","in":"query","description":"Current user's password confirmation.","required":false,"schema":{"type":"string","default":""}}],"responses":{"200":{"description":"The sanitized updated client record and a newly generated plaintext secret when the client becomes confidential.\n\nExample responses require Super User access. Use Try it out to see a live response."},"400":{"$ref":"#\/components\/responses\/BadRequest"},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"},"500":{"$ref":"#\/components\/responses\/ServerError"},"default":{"$ref":"#\/components\/responses\/DefaultError"}}}},"\/index.php?module=API&method=OAuth2.rotateSecret":{"get":{"tags":["OAuth2"],"description":"Generates and persists a new secret for the given OAuth2 client (super users only).","operationId":"OAuth2.rotateSecret","parameters":[{"$ref":"#\/components\/parameters\/formatOptional"},{"name":"clientId","in":"query","description":"32-character hexadecimal client identifier.","required":true,"schema":{"type":"string","example":"0123456789abcdef0123456789abcdef"}},{"name":"passwordConfirmation","in":"query","description":"Current user's password confirmation.","required":false,"schema":{"type":"string","default":""}}],"responses":{"200":{"description":"The client ID and the newly generated plaintext secret.\n\nExample responses require Super User access. Use Try it out to see a live response."},"400":{"$ref":"#\/components\/responses\/BadRequest"},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"},"500":{"$ref":"#\/components\/responses\/ServerError"},"default":{"$ref":"#\/components\/responses\/DefaultError"}}}},"\/index.php?module=API&method=OAuth2.setClientActive":{"get":{"tags":["OAuth2"],"description":"Updates whether an OAuth2 client is active (super users only).","operationId":"OAuth2.setClientActive","parameters":[{"$ref":"#\/components\/parameters\/formatOptional"},{"name":"clientId","in":"query","description":"32-character hexadecimal client identifier.","required":true,"schema":{"type":"string","example":"0123456789abcdef0123456789abcdef"}},{"name":"active","in":"query","description":"`'1'` to enable the client or `'0'` to disable it.","required":true,"schema":{"type":"string","example":"1"}}],"responses":{"200":{"description":"The sanitized client record after the active flag is updated.\n\nExample responses require Super User access. Use Try it out to see a live response."},"400":{"$ref":"#\/components\/responses\/BadRequest"},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"},"500":{"$ref":"#\/components\/responses\/ServerError"},"default":{"$ref":"#\/components\/responses\/DefaultError"}}}},"\/index.php?module=API&method=OAuth2.deleteClient":{"get":{"tags":["OAuth2"],"description":"Deletes an OAuth2 client and its related access tokens, refresh tokens, and auth codes (super users only).","operationId":"OAuth2.deleteClient","parameters":[{"$ref":"#\/components\/parameters\/formatOptional"},{"name":"clientId","in":"query","description":"32-character hexadecimal client identifier.","required":true,"schema":{"type":"string","example":"0123456789abcdef0123456789abcdef"}},{"name":"passwordConfirmation","in":"query","description":"Current user's password confirmation.","required":false,"schema":{"type":"string","default":""}}],"responses":{"200":{"description":"Confirmation that the client and its related OAuth2 records were deleted.\n\nExample responses require Super User access. Use Try it out to see a live response."},"400":{"$ref":"#\/components\/responses\/BadRequest"},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"},"500":{"$ref":"#\/components\/responses\/ServerError"},"default":{"$ref":"#\/components\/responses\/DefaultError"}}}}},"components":{"schemas":{"GenericSuccess":{"description":"Generic Matomo success payload.","required":["result","message"],"properties":{"result":{"type":"string","example":"success"},"message":{"type":"string","example":"ok"},"code":{"type":"integer","example":"200"}},"type":"object","example":{"result":"success","message":"ok"},"additionalProperties":true},"GenericSuccessXml":{"description":"Generic Matomo success payload in XML.","required":["success"],"properties":{"success":{"properties":{"message":{"type":"string","xml":{"attribute":true},"example":"ok"}},"type":"object","xml":{"name":"success"}}},"type":"object","xml":{"name":"result"},"example":{"success":{"message":"ok"}},"additionalProperties":true},"Error":{"description":"Generic Matomo error payload.","required":["result","message"],"properties":{"result":{"type":"string","example":"error"},"message":{"type":"string","example":"There was an error"},"code":{"type":"integer"}},"type":"object","additionalProperties":true},"ErrorXml":{"description":"Generic Matomo error payload in XML.","properties":{"error":{"properties":{"message":{"type":"string","xml":{"attribute":true},"example":"There was an error"}},"type":"object","xml":{"name":"error"}}},"type":"object","xml":{"name":"result"}}},"responses":{"BadRequest":{"description":"Bad request (validation or missing parameters).","content":{"text\/plain":{"schema":{"type":"string"},"example":"Error: There was an error."},"text\/html":{"schema":{"type":"string"},"example":"There was an error."},"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}},"application\/xml":{"schema":{"$ref":"#\/components\/schemas\/ErrorXml"}}}},"Unauthorized":{"description":"Authentication failed or missing token.","content":{"text\/plain":{"schema":{"type":"string"},"example":"Error: You must be logged in to access this functionality."},"text\/html":{"schema":{"type":"string"},"example":"You must be logged in to access this functionality."},"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}},"application\/xml":{"schema":{"$ref":"#\/components\/schemas\/ErrorXml"}}}},"Forbidden":{"description":"Authenticated but not allowed to access the resource.","content":{"text\/plain":{"schema":{"type":"string"},"example":"Error: Not authorised."},"text\/html":{"schema":{"type":"string"},"example":"Not authorised."},"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}},"application\/xml":{"schema":{"$ref":"#\/components\/schemas\/ErrorXml"}}}},"NotFound":{"description":"Resource not found.","content":{"text\/plain":{"schema":{"type":"string"},"example":"Error: The method is not available."},"text\/html":{"schema":{"type":"string"},"example":"The method is not available."},"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}},"application\/xml":{"schema":{"$ref":"#\/components\/schemas\/ErrorXml"}}}},"ServerError":{"description":"Unexpected server error.","content":{"text\/plain":{"schema":{"type":"string"},"example":"Error: There was an error."},"text\/html":{"schema":{"type":"string"},"example":"There was an error."},"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}},"application\/xml":{"schema":{"$ref":"#\/components\/schemas\/ErrorXml"}}}},"DefaultError":{"description":"Default error response (any non-2xx).","content":{"text\/plain":{"schema":{"type":"string"},"example":"Error: There was an error."},"text\/html":{"schema":{"type":"string"},"example":"There was an error."},"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}},"application\/xml":{"schema":{"$ref":"#\/components\/schemas\/ErrorXml"}}}},"GenericSuccessNoBody":{"description":"Generic 200 response with no body"},"GenericSuccess":{"description":"Generic 200 response","content":{"text\/plain":{"schema":{"type":"string"},"example":"Success:ok"},"text\/html":{"schema":{"type":"string"},"example":"<!-- Success: ok -->"},"application\/json":{"schema":{"$ref":"#\/components\/schemas\/GenericSuccess"}},"application\/xml":{"schema":{"$ref":"#\/components\/schemas\/GenericSuccessXml"}}}},"GenericString":{"description":"Generic 200 response with only a string body","content":{"text\/plain":{"schema":{"type":"string"},"example":"Result: success"},"text\/html":{"schema":{"type":"string"},"example":"success"},"application\/json":{"schema":{"type":"string"}},"application\/xml":{"schema":{"type":"string"}}}},"GenericBoolean":{"description":"Generic 200 response with only true or false as the body","content":{"text\/plain":{"schema":{"type":"boolean"}},"text\/html":{"schema":{"type":"boolean"}},"application\/json":{"schema":{"type":"boolean"}},"application\/xml":{"schema":{"type":"boolean"}}}},"GenericInteger":{"description":"Generic 200 response with only an integer as the body","content":{"text\/plain":{"schema":{"type":"integer"}},"text\/html":{"schema":{"type":"integer"}},"application\/json":{"schema":{"type":"integer"}},"application\/xml":{"schema":{"type":"integer"}}}},"GenericArray":{"description":"Generic 200 response with array body","content":{"text\/plain":{"schema":{"type":"string"}},"text\/html":{"schema":{"type":"string"}},"application\/json":{"schema":{"type":"array","items":[]}},"application\/xml":{"schema":{"type":"array","items":[]}}}}},"parameters":{"moduleRequired":{"name":"module","in":"query","description":"Always `API` for Reporting API requests.","required":true,"schema":{"type":"string","default":"API"}},"methodRequired":{"name":"method","in":"query","description":"API method, e.g. `VisitsSummary.get` or `CustomAlerts.getAlert`.","required":true,"schema":{"type":"string","example":"CustomAlerts.getAlert"}},"formatRequired":{"name":"format","in":"query","description":"Response format such as `xml` or `json`. Use `original` to get the original PHP data structure.","required":true,"schema":{"type":"string","default":"xml","enum":["xml","json","csv","tsv","html","rss","original"]}},"formatOptional":{"name":"format","in":"query","description":"Response format. Defaults to `xml`. Use `original` to get the original PHP data structure.","required":false,"schema":{"type":"string","default":"xml","enum":["xml","json","csv","tsv","html","rss","original"]}},"idSiteRequired":{"name":"idSite","in":"query","description":"Matomo site ID.","required":true,"schema":{"type":"integer","example":1}},"idSiteOptional":{"name":"idSite","in":"query","description":"Matomo site ID.","required":false,"schema":{"type":"integer","example":1}},"periodRequired":{"name":"period","in":"query","description":"Reporting period.","required":true,"schema":{"type":"string","enum":["day","week","month","year","range"],"example":"day"}},"periodOptional":{"name":"period","in":"query","description":"Reporting period.","required":false,"schema":{"type":"string","enum":["day","week","month","year","range"],"example":"day"}},"dateRequired":{"name":"date","in":"query","description":"Date or range (e.g. `2025-08-01`, `yesterday`, `last30`, or `2025-08-01,2025-08-11`).","required":true,"schema":{"type":"string","example":"today"}},"dateOptional":{"name":"date","in":"query","description":"Date or range (e.g. `2025-08-01`, `yesterday`, `last30`, or `2025-08-01,2025-08-11`).","required":false,"schema":{"type":"string","example":"today"}},"segmentRequired":{"name":"segment","in":"query","description":"Segment expression; see `API.getSegmentDimensionMetadata`.","required":true,"schema":{"type":"string"}},"segmentOptional":{"name":"segment","in":"query","description":"Segment expression; see `API.getSegmentDimensionMetadata`.","required":false,"schema":{"type":"string"}},"expandedOptional":{"name":"expanded","in":"query","description":"If true, loads all subtables.","required":false,"schema":{"type":"integer","default":0,"enum":[0,1],"example":0}},"idSubtableOptional":{"name":"idSubtable","in":"query","description":"An in-database subtable ID.","required":false,"schema":{"type":"integer"}},"idSubtableRequired":{"name":"idSubtable","in":"query","description":"An in-database subtable ID.","required":true,"schema":{"type":"integer"}},"flatOptional":{"name":"flat","in":"query","description":"Flatten subtables into the parent table.","required":false,"schema":{"type":"integer","enum":[0,1],"example":0}},"filter_patternOptional":{"name":"filter_pattern","in":"query","description":"Regex to keep matching rows.","required":false,"schema":{"type":"string"}},"filter_columnOptional":{"name":"filter_column","in":"query","description":"Column to apply the regex to (e.g., `label`).","required":false,"schema":{"type":"string","example":"label"}},"filter_pattern_recursiveOptional":{"name":"filter_pattern_recursive","in":"query","description":"Recursive regex filter.","required":false,"schema":{"type":"string"}},"filter_column_recursiveOptional":{"name":"filter_column_recursive","in":"query","description":"Column for the recursive regex filter.","required":false,"schema":{"type":"string"}},"filter_excludelowpopOptional":{"name":"filter_excludelowpop","in":"query","description":"Column to threshold and exclude low values.","required":false,"schema":{"type":"string"}},"filter_excludelowpop_valueOptional":{"name":"filter_excludelowpop_value","in":"query","description":"Minimum value threshold for `filter_excludelowpop`.","required":false,"schema":{"type":"number","example":0}},"filter_sort_columnOptional":{"name":"filter_sort_column","in":"query","description":"Column to sort by.","required":false,"schema":{"type":"string"}},"filter_sort_orderOptional":{"name":"filter_sort_order","in":"query","description":"Sort direction.","required":false,"schema":{"type":"string","enum":["asc","desc"],"example":"desc"}},"filter_truncateOptional":{"name":"filter_truncate","in":"query","description":"Row index after which rows are removed.","required":false,"schema":{"type":"integer"}},"filter_limitOptional":{"name":"filter_limit","in":"query","description":"Maximum number of rows to return.","required":false,"schema":{"type":"integer"}},"filter_offsetOptional":{"name":"filter_offset","in":"query","description":"Row offset.","required":false,"schema":{"type":"integer"}},"keep_summary_rowOptional":{"name":"keep_summary_row","in":"query","description":"Keep the summary row.","required":false,"schema":{"type":"integer","enum":[0,1],"example":1}},"disable_generic_filtersOptional":{"name":"disable_generic_filters","in":"query","description":"Disable generic filters (those above).","required":false,"schema":{"type":"integer","enum":[0,1],"example":0}},"disable_queued_filtersOptional":{"name":"disable_queued_filters","in":"query","description":"Skip queued filters.","required":false,"schema":{"type":"integer","enum":[0,1],"example":0}},"hideColumnsOptional":{"name":"hideColumns","in":"query","description":"Comma-separated list of columns to hide.","required":false,"schema":{"type":"string"}},"showColumnsOptional":{"name":"showColumns","in":"query","description":"Comma-separated list of columns to include.","required":false,"schema":{"type":"string"}},"labelOptional":{"name":"label","in":"query","description":"Keep only rows with these label(s). Supports path via '>' and arrays.","required":false,"schema":{"type":"string"}},"idGoalRequired":{"name":"idGoal","in":"query","description":"The ID of a configured goal.","required":true,"schema":{"type":"integer"}},"idGoalOptional":{"name":"idGoal","in":"query","description":"The ID of a configured goal.","required":false,"schema":{"type":"integer"}}},"securitySchemes":{"MatomoToken":{"type":"http","description":"Paste your token generated from Personal > Security. Swagger will send it as a Bearer token.","scheme":"bearer"}}},"security":[{"MatomoToken":[]}],"tags":[{"name":"OAuth2","description":"Exposes super-user OAuth2 client management endpoints for Matomo.  This API lists configured scopes and lets administrators create, inspect, update, rotate, activate, and delete OAuth2 clients."}],"externalDocs":{"description":"Matomo Reporting API developer page","url":"https:\/\/developer.matomo.org\/api-reference\/reporting-api\/"}}