# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Clerk Frontend External Accounts API
  version: 1.0.0
extends: openapi/clerk-com-external-accounts-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 4
- target: $.paths['/v1/me/external_accounts'].post
  update:
    x-apievangelist-phrasing:
      intent: Connect a social login account to my profile
      effect: write
      questions:
      - How do I link a social login account to my existing profile?
      - Can I request extra OAuth scopes when connecting a new external account?
      instructions:
      - text: Connect a new external account using strategy {strategy} and redirect to {redirect_url}.
        slots:
          strategy: requestBody.strategy
          redirect_url: requestBody.redirect_url
      - text: Link an account via {strategy} with additional scopes {additional_scope}.
        slots:
          strategy: requestBody.strategy
          additional_scope: requestBody.additional_scope
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/me/external_accounts/{external_account_id}/reauthorize'].patch
  update:
    x-apievangelist-phrasing:
      intent: Reauthorize a connected external account
      effect: write
      questions:
      - How do I re-consent a connected account to grant new scopes?
      - What do I do when a linked social account's authorization has lapsed?
      instructions:
      - text: Reauthorize external account {external_account_id} and redirect to {redirect_url}.
        slots:
          external_account_id: path.external_account_id
          redirect_url: requestBody.redirect_url
      - text: Reauthorize {external_account_id} with extra scopes {additional_scope}, returning to {redirect_url}.
        slots:
          external_account_id: path.external_account_id
          additional_scope: requestBody.additional_scope
          redirect_url: requestBody.redirect_url
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/me/external_accounts/{external_account_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Unlink an external account from my profile
      effect: destructive
      questions:
      - How do I disconnect a social login from my account?
      - Can I remove a linked external account entirely?
      instructions:
      - text: Delete external account {external_account_id}.
        slots:
          external_account_id: path.external_account_id
      - text: Unlink connected account {external_account_id} from my profile.
        slots:
          external_account_id: path.external_account_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/me/external_accounts/{external_account_id}/tokens'].delete
  update:
    x-apievangelist-phrasing:
      intent: Revoke OAuth tokens of a linked account
      effect: destructive
      questions:
      - How do I revoke the access and refresh tokens stored for a linked account but keep the link?
      - Does revoking tokens for a connected account work with every provider?
      instructions:
      - text: Revoke the OAuth tokens for external account {external_account_id}.
        slots:
          external_account_id: path.external_account_id
      - text: Invalidate stored access and refresh tokens of {external_account_id}.
        slots:
          external_account_id: path.external_account_id
      method: generated
      generated: '2026-09-26'