# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Matomo Reporting API for plugin O Auth2 API
  version: 1.0.0
extends: openapi/matomo-oauth2-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 8
- target: $.paths['/index.php?module=API&method=OAuth2.getClients'].get
  update:
    x-apievangelist-phrasing:
      intent: List OAuth2 clients
      effect: read
      questions:
      - Which OAuth2 client applications are configured in my Matomo?
      - Can a super user see every OAuth client that has API access?
      instructions:
      - text: List all configured OAuth2 clients.
      - text: Show every OAuth client app registered on this instance.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=OAuth2.getClient'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one OAuth2 client
      effect: read
      questions:
      - What grant types and redirect URIs does a specific OAuth client have?
      - Is a particular OAuth2 client still active?
      instructions:
      - text: Get OAuth2 client {clientId}.
        slots:
          clientId: query.clientId
      - text: Show the scopes, grant types and redirect URIs of OAuth client {clientId}.
        slots:
          clientId: query.clientId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=OAuth2.getScopes'].get
  update:
    x-apievangelist-phrasing:
      intent: List the OAuth2 scopes available to clients
      effect: read
      questions:
      - What scopes can I grant to an OAuth2 client?
      - Which OAuth permission scopes are enabled for client configuration?
      instructions:
      - text: List the OAuth2 scopes enabled for clients.
      - text: Show which permission scopes I can assign to an OAuth app.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=OAuth2.createClient'].get
  update:
    x-apievangelist-phrasing:
      intent: Create an OAuth2 client
      effect: write
      questions:
      - How do I register a new OAuth2 app so it can call the Matomo API?
      - Can I create a client with the client credentials grant and get its secret back?
      instructions:
      - text: Create an OAuth2 client named {name} with grant types {grantTypes} and scope {scope}.
        slots:
          name: query.name
          grantTypes: query.grantTypes
          scope: query.scope
      - text: Register OAuth app {name} using {grantTypes}, scope {scope}, redirecting to {redirectUris}.
        slots:
          name: query.name
          grantTypes: query.grantTypes
          scope: query.scope
          redirectUris: query.redirectUris
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=OAuth2.updateClient'].get
  update:
    x-apievangelist-phrasing:
      intent: Update an OAuth2 client
      effect: write
      questions:
      - How do I change the redirect URIs or scope on an existing OAuth client?
      - Can I edit an OAuth app's name and grant types after creating it?
      instructions:
      - text: 'Update OAuth2 client {clientId}: name {name}, grant types {grantTypes}, scope {scope}.'
        slots:
          clientId: query.clientId
          name: query.name
          grantTypes: query.grantTypes
          scope: query.scope
      - text: Change the redirect URIs of existing client {clientId} to {redirectUris}, keeping name {name}, grants {grantTypes} and scope {scope}.
        slots:
          clientId: query.clientId
          redirectUris: query.redirectUris
          name: query.name
          grantTypes: query.grantTypes
          scope: query.scope
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=OAuth2.rotateSecret'].get
  update:
    x-apievangelist-phrasing:
      intent: Rotate an OAuth2 client's secret
      effect: destructive
      questions:
      - How do I generate a new secret for an OAuth client whose secret leaked?
      - Will rotating a client secret replace the old one?
      instructions:
      - text: Rotate the secret for OAuth2 client {clientId}.
        slots:
          clientId: query.clientId
      - text: Generate a fresh client secret for {clientId}, confirming with password {passwordConfirmation}.
        slots:
          clientId: query.clientId
          passwordConfirmation: query.passwordConfirmation
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=OAuth2.setClientActive'].get
  update:
    x-apievangelist-phrasing:
      intent: Activate or deactivate an OAuth2 client
      effect: write
      questions:
      - Can I temporarily disable an OAuth client without deleting it?
      - How do I re-enable an OAuth app I switched off?
      instructions:
      - text: Set OAuth2 client {clientId} active to {active}.
        slots:
          clientId: query.clientId
          active: query.active
      - text: Deactivate OAuth client {clientId} by setting active={active}.
        slots:
          clientId: query.clientId
          active: query.active
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=OAuth2.deleteClient'].get
  update:
    x-apievangelist-phrasing:
      intent: Delete an OAuth2 client and its tokens
      effect: destructive
      questions:
      - What happens to access and refresh tokens when I delete an OAuth client?
      - How do I permanently remove an OAuth app from Matomo?
      instructions:
      - text: Delete OAuth2 client {clientId}.
        slots:
          clientId: query.clientId
      - text: Remove OAuth client {clientId} and all its tokens, confirming with password {passwordConfirmation}.
        slots:
          clientId: query.clientId
          passwordConfirmation: query.passwordConfirmation
      method: generated
      generated: '2026-10-01'