# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for GitHub v3 REST OAUTH Authorizations API
  version: 1.0.0
extends: openapi/github-oauth-authorizations-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-24'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 10
- target: $.paths['/applications/grants'].get
  update:
    x-apievangelist-phrasing:
      intent: List the OAuth apps I've granted access
      effect: read
      questions:
      - Which OAuth applications have I granted access to my account?
      - Can I list my grants for just one OAuth app client ID?
      instructions:
      - text: List all OAuth grants on my account.
      - text: Show my OAuth grants for client ID {client_id}.
        slots:
          client_id: query.client_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/applications/grants/{grant_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one OAuth grant
      effect: read
      questions:
      - What scopes did I grant a particular OAuth app?
      - Can I look up a single application grant by its ID?
      instructions:
      - text: Get OAuth grant {grant_id}.
        slots:
          grant_id: path.grant_id
      - text: Show the app and scopes behind grant {grant_id}.
        slots:
          grant_id: path.grant_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/applications/grants/{grant_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Revoke an OAuth grant and its tokens
      effect: destructive
      questions:
      - How do I cut off an OAuth app's access to my account entirely?
      - Does deleting a grant also revoke all of that app's tokens for me?
      instructions:
      - text: Delete OAuth grant {grant_id}.
        slots:
          grant_id: path.grant_id
      - text: Revoke application grant {grant_id} and every token under it.
        slots:
          grant_id: path.grant_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/authorizations'].get
  update:
    x-apievangelist-phrasing:
      intent: List my OAuth authorizations
      effect: read
      questions:
      - What OAuth tokens and authorizations exist on my account?
      - Can I filter my authorizations down to one OAuth app?
      instructions:
      - text: List my OAuth authorizations.
      - text: Show my authorizations created for OAuth client {client_id}.
        slots:
          client_id: query.client_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/authorizations'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new OAuth authorization (deprecated)
      effect: write
      questions:
      - Can I still create a personal token through the OAuth Authorizations API?
      - What should I use instead now that creating authorizations is deprecated?
      instructions:
      - text: Create an OAuth authorization with scopes {scopes} and note {note}.
        slots:
          scopes: requestBody.scopes
          note: requestBody.note
      - text: Create a new authorization for client {client_id} using secret {client_secret} with fingerprint {fingerprint}.
        slots:
          client_id: requestBody.client_id
          client_secret: requestBody.client_secret
          fingerprint: requestBody.fingerprint
      method: generated
      generated: '2026-09-24'
- target: $.paths['/authorizations/clients/{client_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Get or create an authorization for an OAuth app
      effect: write
      questions:
      - Can I reuse an existing authorization for an OAuth app instead of making a duplicate?
      - What happens if an authorization for this app client already exists?
      instructions:
      - text: Get or create an authorization for app {client_id} using secret {client_secret}.
        slots:
          client_id: path.client_id
          client_secret: requestBody.client_secret
      - text: Ensure an authorization exists for client {client_id} with secret {client_secret} and scopes {scopes}.
        slots:
          client_id: path.client_id
          client_secret: requestBody.client_secret
          scopes: requestBody.scopes
      method: generated
      generated: '2026-09-24'
- target: $.paths['/authorizations/clients/{client_id}/{fingerprint}'].put
  update:
    x-apievangelist-phrasing:
      intent: Get or create an app authorization by fingerprint
      effect: write
      questions:
      - Can I keep separate authorizations for the same app per device using a fingerprint?
      - How does the fingerprint distinguish authorizations for one client ID?
      instructions:
      - text: Get or create the authorization for app {client_id} and fingerprint {fingerprint} using secret {client_secret}.
        slots:
          client_id: path.client_id
          fingerprint: path.fingerprint
          client_secret: requestBody.client_secret
      - text: Ensure a per-device authorization tagged {fingerprint} exists for client {client_id} (secret {client_secret}).
        slots:
          fingerprint: path.fingerprint
          client_id: path.client_id
          client_secret: requestBody.client_secret
      method: generated
      generated: '2026-09-24'
- target: $.paths['/authorizations/{authorization_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one OAuth authorization
      effect: read
      questions:
      - What scopes and note are attached to one of my authorizations?
      - Can I look up a single OAuth authorization by its ID?
      instructions:
      - text: Get OAuth authorization {authorization_id}.
        slots:
          authorization_id: path.authorization_id
      - text: Show the scopes and note on authorization {authorization_id}.
        slots:
          authorization_id: path.authorization_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/authorizations/{authorization_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an OAuth authorization
      effect: destructive
      questions:
      - How do I revoke one specific OAuth authorization on my account?
      - Is deleting a single authorization different from deleting the whole grant?
      instructions:
      - text: Delete OAuth authorization {authorization_id}.
        slots:
          authorization_id: path.authorization_id
      - text: Revoke the single authorization {authorization_id} from my account.
        slots:
          authorization_id: path.authorization_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/authorizations/{authorization_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change an OAuth authorization's scopes or note
      effect: write
      questions:
      - Can I add a scope to an existing authorization without recreating it?
      - How do I drop a scope from one of my OAuth authorizations?
      instructions:
      - text: Add scopes {add_scopes} to authorization {authorization_id}.
        slots:
          add_scopes: requestBody.add_scopes
          authorization_id: path.authorization_id
      - text: Remove scopes {remove_scopes} from authorization {authorization_id}.
        slots:
          remove_scopes: requestBody.remove_scopes
          authorization_id: path.authorization_id
      - text: Change the note on authorization {authorization_id} to {note}.
        slots:
          authorization_id: path.authorization_id
          note: requestBody.note
      method: generated
      generated: '2026-09-24'