# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Identity.SignIns Oauth2 Permission Grants.o Auth2…
  version: 1.0.0
extends: openapi/azure-ad-oauth2permissiongrants-oauth2permissiongrant-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: 6
- target: $.paths['/oauth2PermissionGrants'].get
  update:
    x-apievangelist-phrasing:
      intent: List delegated permission grants
      effect: read
      questions:
      - Which client apps have been granted delegated permissions to call APIs for signed-in users?
      - How do I audit every OAuth2 consent grant in my tenant?
      - Can I filter delegated grants down to a single client app?
      instructions:
      - text: List all delegated permission grants in the tenant.
      - text: List delegated permission grants matching {filter}.
        slots:
          filter: query.$filter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/oauth2PermissionGrants'].post
  update:
    x-apievangelist-phrasing:
      intent: Grant delegated permissions to a client app
      effect: write
      questions:
      - How do I programmatically consent to delegated scopes for an app on behalf of all users?
      - Can I grant a client service principal access to an API for just one user?
      instructions:
      - text: Grant client {client_id} the delegated scopes {scope} on resource {resource_id} for all principals.
        slots:
          client_id: requestBody.clientId
          scope: requestBody.scope
          resource_id: requestBody.resourceId
      - text: Create a delegated grant with consent type {consent_type} letting client {client_id} access {resource_id} as user {principal_id} with scopes {scope}.
        slots:
          consent_type: requestBody.consentType
          client_id: requestBody.clientId
          resource_id: requestBody.resourceId
          principal_id: requestBody.principalId
          scope: requestBody.scope
      method: generated
      generated: '2026-10-01'
- target: $.paths['/oauth2PermissionGrants/{oAuth2PermissionGrant-id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one delegated permission grant
      effect: read
      questions:
      - What scopes does a specific delegated permission grant cover?
      - How do I check whether a particular consent grant is for all principals or one user?
      instructions:
      - text: Show delegated permission grant {grant_id}.
        slots:
          grant_id: path.oAuth2PermissionGrant-id
      - text: Tell me the client, resource and scopes on grant {grant_id}.
        slots:
          grant_id: path.oAuth2PermissionGrant-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/oauth2PermissionGrants/{oAuth2PermissionGrant-id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Revoke a delegated permission grant
      effect: destructive
      questions:
      - How do I revoke consent an app was given to act on users' behalf?
      - Do existing access tokens stop working immediately when I remove a delegated grant?
      instructions:
      - text: Revoke delegated permission grant {grant_id}.
        slots:
          grant_id: path.oAuth2PermissionGrant-id
      - text: Delete consent grant {grant_id} so no new tokens are issued for its scopes.
        slots:
          grant_id: path.oAuth2PermissionGrant-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/oauth2PermissionGrants/{oAuth2PermissionGrant-id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change the scopes on a delegated grant
      effect: write
      questions:
      - Can I add or remove scopes on a consent grant that already exists?
      - How do I narrow an existing delegated grant to fewer permissions?
      instructions:
      - text: Set the scopes on existing grant {grant_id} to {scope}.
        slots:
          grant_id: path.oAuth2PermissionGrant-id
          scope: requestBody.scope
      - text: Remove every scope except User.Read from delegated grant {grant_id}.
        slots:
          grant_id: path.oAuth2PermissionGrant-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/oauth2PermissionGrants/$count'].get
  update:
    x-apievangelist-phrasing:
      intent: Count delegated permission grants
      effect: read
      questions:
      - How many delegated permission grants exist across my tenant?
      - What's the count of consent grants that match a filter such as a consent type?
      instructions:
      - text: Count the delegated permission grants.
      - text: Count delegated grants where {filter}.
        slots:
          filter: query.$filter
      method: generated
      generated: '2026-10-01'