# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Live Direct Marketing Online OAuth API
  version: 1.0.0
extends: openapi/live-direct-marketing-online-oauth-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: 11
- target: $.paths['/api/oauth/authorize'].get
  update:
    x-apievangelist-phrasing:
      intent: Open the OAuth authorization page
      effect: read
      questions:
      - How does a third-party app start the OAuth authorization flow?
      - Can my client use PKCE with a code challenge when sending users to authorize?
      instructions:
      - text: Open the authorize page for client {client_id} redirecting to {redirect_uri}.
        slots:
          client_id: query.client_id
          redirect_uri: query.redirect_uri
      - text: Start authorization for client {client_id} with response type {response_type} and scope {scope}.
        slots:
          client_id: query.client_id
          response_type: query.response_type
          scope: query.scope
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/oauth/authorize'].post
  update:
    x-apievangelist-phrasing:
      intent: Sign in and grant an OAuth client access
      effect: write
      questions:
      - What happens when a user submits their login on the OAuth consent form?
      - Can a user approve an app's access with their email and password?
      instructions:
      - text: Approve client {client_id} for {email} with password {password}, redirecting to {redirect_uri}.
        slots:
          client_id: requestBody.client_id
          email: requestBody.email
          password: requestBody.password
          redirect_uri: requestBody.redirect_uri
      - text: Submit the consent form granting scope {scope} to client {client_id}.
        slots:
          scope: requestBody.scope
          client_id: requestBody.client_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/oauth/token'].post
  update:
    x-apievangelist-phrasing:
      intent: Exchange a code or refresh token for an access token
      effect: write
      questions:
      - How does my app exchange an authorization code for an access token?
      - Can I use a refresh token grant to get a new access token?
      instructions:
      - text: Exchange code {code} for a token as client {client_id} with secret {client_secret}.
        slots:
          code: requestBody.code
          client_id: requestBody.client_id
          client_secret: requestBody.client_secret
      - text: Get a new access token with refresh token {refresh_token} for client {client_id}.
        slots:
          refresh_token: requestBody.refresh_token
          client_id: requestBody.client_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/oauth/me'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the user behind an OAuth token
      effect: read
      questions:
      - Which user does my OAuth access token belong to?
      - Can an app read the profile of the person who authorized it?
      instructions:
      - text: Show the user tied to my OAuth access token.
      - text: Identify who authorized this OAuth app.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/oauth/connect'].get
  update:
    x-apievangelist-phrasing:
      intent: Open the public mailbox connect page
      effect: read
      questions:
      - Is there a public page for connecting mailboxes through the anti-detect browser flow?
      - How do I share a connect link for a tenant's mailboxes?
      instructions:
      - text: Open the mailbox connect page with key {key} for tenant {tenant}.
        slots:
          key: query.key
          tenant: query.tenant
      - text: Load the public OAuth connect page for tenant {tenant}.
        slots:
          tenant: query.tenant
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/oauth/connect/{accountId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Redirect to OAuth consent for one mailbox
      effect: read
      questions:
      - Can I send someone straight to the consent screen for one specific mailbox?
      - What public link starts OAuth consent for a single account?
      instructions:
      - text: Redirect to consent for account {accountId} using key {key} and tenant {tenant}.
        slots:
          accountId: path.accountId
          key: query.key
          tenant: query.tenant
      - text: Start the public consent redirect for mailbox {accountId}.
        slots:
          accountId: path.accountId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/oauth/auth-url/{accountId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the OAuth consent URL for a mailbox
      effect: read
      questions:
      - Where do I get the consent URL to connect a mailbox with OAuth?
      - Can I generate an authorization link for a specific mail provider?
      instructions:
      - text: Get the OAuth consent URL for account {accountId} with provider {provider}.
        slots:
          accountId: path.accountId
          provider: query.provider
      - text: Build the authorization link for mailbox {accountId}.
        slots:
          accountId: path.accountId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/oauth/callback'].get
  update:
    x-apievangelist-phrasing:
      intent: Handle the mail provider's OAuth callback
      effect: write
      questions:
      - Which endpoint does the mail provider redirect back to after consent?
      - What happens if the provider returns an error to the OAuth callback?
      instructions:
      - text: Complete the OAuth callback with code {code} and state {state}.
        slots:
          code: query.code
          state: query.state
      - text: Process the provider callback that returned error {error}.
        slots:
          error: query.error
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/oauth/{accountId}/status'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a mailbox's OAuth connection status
      effect: read
      questions:
      - Is a mailbox still connected through OAuth?
      - Has the OAuth token on an account expired?
      instructions:
      - text: Check the OAuth status of account {accountId}.
        slots:
          accountId: path.accountId
      - text: Tell me whether mailbox {accountId} is still OAuth-connected.
        slots:
          accountId: path.accountId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/oauth/{accountId}/revoke'].post
  update:
    x-apievangelist-phrasing:
      intent: Revoke a mailbox's OAuth tokens
      effect: destructive
      questions:
      - How do I disconnect a mailbox's OAuth access?
      - Can I revoke the stored tokens for an account?
      instructions:
      - text: Revoke the OAuth tokens for account {accountId}.
        slots:
          accountId: path.accountId
      - text: Disconnect OAuth on mailbox {accountId}.
        slots:
          accountId: path.accountId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/oauth/{accountId}/refresh'].post
  update:
    x-apievangelist-phrasing:
      intent: Refresh a mailbox's OAuth access token
      effect: write
      questions:
      - Can I force a refresh of a mailbox's access token?
      - What should I do when an account's OAuth token needs renewing now?
      instructions:
      - text: Refresh the OAuth access token for account {accountId}.
        slots:
          accountId: path.accountId
      - text: Manually renew the token on mailbox {accountId}.
        slots:
          accountId: path.accountId
      method: generated
      generated: '2026-10-01'