# 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 Policies.permission Grant Policy API
  version: 1.0.0
extends: openapi/azure-ad-policies-permissiongrantpolicy-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: 18
- target: $.paths['/policies/permissionGrantPolicies'].get
  update:
    x-apievangelist-phrasing:
      intent: List permission grant policies
      effect: read
      questions:
      - Which permission grant policies control app consent in my tenant?
      - Can I see both the built-in and custom consent policies in one list?
      instructions:
      - text: List the permission grant policies.
      - text: List permission grant policies matching {filter}.
        slots:
          filter: query.$filter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/policies/permissionGrantPolicies'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a permission grant policy
      effect: write
      questions:
      - How do I define a custom policy for when users may consent to apps?
      - Can I create a consent policy first and add its include and exclude rules afterwards?
      instructions:
      - text: Create a new permission grant policy for app consent.
      - text: Create a permission grant policy with include condition sets {includes} and exclude condition sets {excludes}.
        slots:
          includes: requestBody.includes
          excludes: requestBody.excludes
      method: generated
      generated: '2026-10-01'
- target: $.paths['/policies/permissionGrantPolicies/{permissionGrantPolicy-id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a permission grant policy
      effect: read
      questions:
      - What conditions does a particular consent policy include and exclude?
      - How do I view one permission grant policy by its id?
      instructions:
      - text: Get permission grant policy {policy_id}.
        slots:
          policy_id: path.permissionGrantPolicy-id
      - text: Show {fields} of consent policy {policy_id}.
        slots:
          fields: query.$select
          policy_id: path.permissionGrantPolicy-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/policies/permissionGrantPolicies/{permissionGrantPolicy-id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a permission grant policy
      effect: destructive
      questions:
      - Can I remove a custom consent policy I no longer need?
      - What's required to delete a permission grant policy by id?
      instructions:
      - text: Delete permission grant policy {policy_id}.
        slots:
          policy_id: path.permissionGrantPolicy-id
      - text: Remove consent policy {policy_id} if its ETag is {etag}.
        slots:
          policy_id: path.permissionGrantPolicy-id
          etag: header.If-Match
      method: generated
      generated: '2026-10-01'
- target: $.paths['/policies/permissionGrantPolicies/{permissionGrantPolicy-id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a permission grant policy
      effect: write
      questions:
      - How do I replace the include and exclude conditions on an existing consent policy in one update?
      - Can I edit a permission grant policy's properties after it's created?
      instructions:
      - text: Update permission grant policy {policy_id} with include condition sets {includes}.
        slots:
          policy_id: path.permissionGrantPolicy-id
          includes: requestBody.includes
      - text: Replace the exclude condition sets on policy {policy_id} with {excludes}.
        slots:
          policy_id: path.permissionGrantPolicy-id
          excludes: requestBody.excludes
      method: generated
      generated: '2026-10-01'
- target: $.paths['/policies/permissionGrantPolicies/{permissionGrantPolicy-id}/excludes'].get
  update:
    x-apievangelist-phrasing:
      intent: List a consent policy's exclude conditions
      effect: read
      questions:
      - Which condition sets are excluded from a permission grant policy?
      - What app consent scenarios does this policy carve out as exceptions?
      instructions:
      - text: List the exclude condition sets on permission grant policy {policy_id}.
        slots:
          policy_id: path.permissionGrantPolicy-id
      - text: Show the exceptions defined in consent policy {policy_id}.
        slots:
          policy_id: path.permissionGrantPolicy-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/policies/permissionGrantPolicies/{permissionGrantPolicy-id}/excludes'].post
  update:
    x-apievangelist-phrasing:
      intent: Add an exclude condition to a consent policy
      effect: write
      questions:
      - How do I exclude a specific client app from a permission grant policy?
      - Can I carve out high-risk permissions so consent to them isn't covered by a policy?
      instructions:
      - text: Exclude client apps {client_app_ids} from permission grant policy {policy_id}.
        slots:
          client_app_ids: requestBody.clientApplicationIds
          policy_id: path.permissionGrantPolicy-id
      - text: Add an exclusion to policy {policy_id} for {permission_type} permissions classified {classification}.
        slots:
          policy_id: path.permissionGrantPolicy-id
          permission_type: requestBody.permissionType
          classification: requestBody.permissionClassification
      method: generated
      generated: '2026-10-01'
- target: $.paths['/policies/permissionGrantPolicies/{permissionGrantPolicy-id}/excludes/{permissionGrantConditionSet-id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one exclude condition set of a policy
      effect: read
      questions:
      - What exactly does a single exclusion rule in a consent policy match?
      - How do I inspect one excluded condition set by id?
      instructions:
      - text: Get exclude condition set {condition_set_id} from policy {policy_id}.
        slots:
          condition_set_id: path.permissionGrantConditionSet-id
          policy_id: path.permissionGrantPolicy-id
      - text: Show the exception rule {condition_set_id} in consent policy {policy_id}.
        slots:
          condition_set_id: path.permissionGrantConditionSet-id
          policy_id: path.permissionGrantPolicy-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/policies/permissionGrantPolicies/{permissionGrantPolicy-id}/excludes/{permissionGrantConditionSet-id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove an exclude condition from a policy
      effect: destructive
      questions:
      - Can I drop an exception rule so a consent policy covers those apps again?
      - How do I delete one condition set from a policy's excludes?
      instructions:
      - text: Delete exclude condition set {condition_set_id} from policy {policy_id}.
        slots:
          condition_set_id: path.permissionGrantConditionSet-id
          policy_id: path.permissionGrantPolicy-id
      - text: Remove the exception {condition_set_id} from consent policy {policy_id}.
        slots:
          condition_set_id: path.permissionGrantConditionSet-id
          policy_id: path.permissionGrantPolicy-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/policies/permissionGrantPolicies/{permissionGrantPolicy-id}/excludes/{permissionGrantConditionSet-id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Edit an exclude condition set of a policy
      effect: write
      questions:
      - Can I change which publishers an existing exclusion rule applies to?
      - How do I update the permissions listed in a policy's exclude condition set?
      instructions:
      - text: Set the publisher ids on exclude condition set {condition_set_id} of policy {policy_id} to {publisher_ids}.
        slots:
          condition_set_id: path.permissionGrantConditionSet-id
          policy_id: path.permissionGrantPolicy-id
          publisher_ids: requestBody.clientApplicationPublisherIds
      - text: Change the excluded permissions in rule {condition_set_id} on policy {policy_id} to {permissions}.
        slots:
          condition_set_id: path.permissionGrantConditionSet-id
          policy_id: path.permissionGrantPolicy-id
          permissions: requestBody.permissions
      method: generated
      generated: '2026-10-01'
- target: $.paths['/policies/permissionGrantPolicies/{permissionGrantPolicy-id}/excludes/$count'].get
  update:
    x-apievangelist-phrasing:
      intent: Count a consent policy's exclude conditions
      effect: read
      questions:
      - How many exception rules does a permission grant policy have?
      - What's the number of excluded condition sets matching a filter?
      instructions:
      - text: Count the exclude condition sets on policy {policy_id}.
        slots:
          policy_id: path.permissionGrantPolicy-id
      - text: Count exclusions on policy {policy_id} where {filter}.
        slots:
          policy_id: path.permissionGrantPolicy-id
          filter: query.$filter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/policies/permissionGrantPolicies/{permissionGrantPolicy-id}/includes'].get
  update:
    x-apievangelist-phrasing:
      intent: List a consent policy's include conditions
      effect: read
      questions:
      - Which condition sets does a permission grant policy include?
      - What kinds of app consent does this policy actually allow?
      instructions:
      - text: List the include condition sets on permission grant policy {policy_id}.
        slots:
          policy_id: path.permissionGrantPolicy-id
      - text: Show the matching rules defined in consent policy {policy_id}.
        slots:
          policy_id: path.permissionGrantPolicy-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/policies/permissionGrantPolicies/{permissionGrantPolicy-id}/includes'].post
  update:
    x-apievangelist-phrasing:
      intent: Add an include condition to a consent policy
      effect: write
      questions:
      - How do I allow consent to low-risk delegated permissions from verified publishers only?
      - Can I add a matching rule for a specific resource application to a consent policy?
      instructions:
      - text: Add an include rule to policy {policy_id} for {permission_type} permissions classified {classification}.
        slots:
          policy_id: path.permissionGrantPolicy-id
          permission_type: requestBody.permissionType
          classification: requestBody.permissionClassification
      - text: Include only verified-publisher apps ({verified_only}) in consent policy {policy_id}.
        slots:
          verified_only: requestBody.clientApplicationsFromVerifiedPublisherOnly
          policy_id: path.permissionGrantPolicy-id
      - text: Add a matching rule to policy {policy_id} for resource app {resource_app}.
        slots:
          policy_id: path.permissionGrantPolicy-id
          resource_app: requestBody.resourceApplication
      method: generated
      generated: '2026-10-01'
- target: $.paths['/policies/permissionGrantPolicies/{permissionGrantPolicy-id}/includes/{permissionGrantConditionSet-id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one include condition set of a policy
      effect: read
      questions:
      - What does a single matching rule in a consent policy allow?
      - How do I inspect one included condition set by its id?
      instructions:
      - text: Get include condition set {condition_set_id} from policy {policy_id}.
        slots:
          condition_set_id: path.permissionGrantConditionSet-id
          policy_id: path.permissionGrantPolicy-id
      - text: Show matching rule {condition_set_id} in consent policy {policy_id}.
        slots:
          condition_set_id: path.permissionGrantConditionSet-id
          policy_id: path.permissionGrantPolicy-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/policies/permissionGrantPolicies/{permissionGrantPolicy-id}/includes/{permissionGrantConditionSet-id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove an include condition from a policy
      effect: destructive
      questions:
      - Can I stop a consent policy from allowing a scenario by deleting one of its matching rules?
      - How do I delete a condition set from a policy's includes?
      instructions:
      - text: Delete include condition set {condition_set_id} from policy {policy_id}.
        slots:
          condition_set_id: path.permissionGrantConditionSet-id
          policy_id: path.permissionGrantPolicy-id
      - text: Remove matching rule {condition_set_id} from consent policy {policy_id}.
        slots:
          condition_set_id: path.permissionGrantConditionSet-id
          policy_id: path.permissionGrantPolicy-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/policies/permissionGrantPolicies/{permissionGrantPolicy-id}/includes/{permissionGrantConditionSet-id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Edit an include condition set of a policy
      effect: write
      questions:
      - Can I restrict an existing matching rule to apps from certain tenants?
      - How do I change the permission classification on a policy's include condition set?
      instructions:
      - text: Limit include rule {condition_set_id} on policy {policy_id} to client tenants {tenant_ids}.
        slots:
          condition_set_id: path.permissionGrantConditionSet-id
          policy_id: path.permissionGrantPolicy-id
          tenant_ids: requestBody.clientApplicationTenantIds
      - text: Set the permission classification on matching rule {condition_set_id} in policy {policy_id} to {classification}.
        slots:
          condition_set_id: path.permissionGrantConditionSet-id
          policy_id: path.permissionGrantPolicy-id
          classification: requestBody.permissionClassification
      method: generated
      generated: '2026-10-01'
- target: $.paths['/policies/permissionGrantPolicies/{permissionGrantPolicy-id}/includes/$count'].get
  update:
    x-apievangelist-phrasing:
      intent: Count a consent policy's include conditions
      effect: read
      questions:
      - How many matching rules are included in a permission grant policy?
      - What's the number of include condition sets that fit a filter?
      instructions:
      - text: Count the include condition sets on policy {policy_id}.
        slots:
          policy_id: path.permissionGrantPolicy-id
      - text: Count matching rules on policy {policy_id} where {filter}.
        slots:
          policy_id: path.permissionGrantPolicy-id
          filter: query.$filter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/policies/permissionGrantPolicies/$count'].get
  update:
    x-apievangelist-phrasing:
      intent: Count permission grant policies
      effect: read
      questions:
      - How many permission grant policies exist in my tenant?
      - What's the total of consent policies that match a filter?
      instructions:
      - text: Count the permission grant policies.
      - text: Count consent policies where {filter}.
        slots:
          filter: query.$filter
      method: generated
      generated: '2026-10-01'