# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Applications Service Principals.app Role Assignment API
  version: 1.0.0
extends: openapi/azure-ad-serviceprincipals-approleassignment-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: 12
- target: $.paths['/servicePrincipals/{servicePrincipal-id}/appRoleAssignedTo'].get
  update:
    x-apievangelist-phrasing:
      intent: List who has been granted an app's roles
      effect: read
      questions:
      - Which users, groups and apps have been granted roles on my API's service principal?
      - Who has access to this enterprise application through its app roles?
      instructions:
      - text: List the app role assignments granted for resource service principal {sp_id}.
        slots:
          sp_id: path.servicePrincipal-id
      - text: Show everyone assigned to the app roles of service principal {sp_id}.
        slots:
          sp_id: path.servicePrincipal-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/servicePrincipals/{servicePrincipal-id}/appRoleAssignedTo'].post
  update:
    x-apievangelist-phrasing:
      intent: Grant a user, group or app a role on a resource app
      effect: write
      questions:
      - How do I give a user or group an app role on an enterprise application?
      - Can I assign a resource app's role to a client service principal from the resource side?
      instructions:
      - text: Assign app role {app_role_id} of resource {sp_id} to principal {principal_id}.
        slots:
          app_role_id: requestBody.appRoleId
          sp_id: path.servicePrincipal-id
          principal_id: requestBody.principalId
      - text: Grant principal {principal_id} access to resource service principal {sp_id} with role {app_role_id}, resource id {resource_id}.
        slots:
          principal_id: requestBody.principalId
          sp_id: path.servicePrincipal-id
          app_role_id: requestBody.appRoleId
          resource_id: requestBody.resourceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/servicePrincipals/{servicePrincipal-id}/appRoleAssignedTo/{appRoleAssignment-id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one grant of a resource app's role
      effect: read
      questions:
      - Who received a specific role assignment on my resource app, and which role was it?
      - When was a particular app role granted on this enterprise app?
      instructions:
      - text: Get assignment {assignment_id} granted on resource service principal {sp_id}.
        slots:
          assignment_id: path.appRoleAssignment-id
          sp_id: path.servicePrincipal-id
      - text: Show the principal and role of assignment {assignment_id} made to resource {sp_id}.
        slots:
          assignment_id: path.appRoleAssignment-id
          sp_id: path.servicePrincipal-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/servicePrincipals/{servicePrincipal-id}/appRoleAssignedTo/{appRoleAssignment-id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Revoke a user, group or app's role on a resource app
      effect: destructive
      questions:
      - How do I remove a user's access to an enterprise application?
      - Can I revoke an app role that a group was granted on my resource app?
      instructions:
      - text: Revoke assignment {assignment_id} from resource service principal {sp_id}.
        slots:
          assignment_id: path.appRoleAssignment-id
          sp_id: path.servicePrincipal-id
      - text: Remove the app role grant {assignment_id} that someone holds on resource {sp_id}.
        slots:
          assignment_id: path.appRoleAssignment-id
          sp_id: path.servicePrincipal-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/servicePrincipals/{servicePrincipal-id}/appRoleAssignedTo/{appRoleAssignment-id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a role grant on a resource app
      effect: write
      questions:
      - Can I change which role a user holds on my resource app without deleting the grant?
      - Is it possible to edit an assignment listed under a resource's appRoleAssignedTo?
      instructions:
      - text: Change assignment {assignment_id} on resource {sp_id} to app role {app_role_id}.
        slots:
          assignment_id: path.appRoleAssignment-id
          sp_id: path.servicePrincipal-id
          app_role_id: requestBody.appRoleId
      - text: Update the appRoleAssignedTo entry {assignment_id} of service principal {sp_id}.
        slots:
          assignment_id: path.appRoleAssignment-id
          sp_id: path.servicePrincipal-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/servicePrincipals/{servicePrincipal-id}/appRoleAssignedTo/$count'].get
  update:
    x-apievangelist-phrasing:
      intent: Count grants of a resource app's roles
      effect: read
      questions:
      - How many users, groups and apps have been granted roles on my resource app?
      - What's the number of assignments to this enterprise app?
      instructions:
      - text: Count the app role assignments granted for resource {sp_id}.
        slots:
          sp_id: path.servicePrincipal-id
      - text: Tell me how many principals are assigned to service principal {sp_id}'s roles.
        slots:
          sp_id: path.servicePrincipal-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/servicePrincipals/{servicePrincipal-id}/appRoleAssignments'].get
  update:
    x-apievangelist-phrasing:
      intent: List app roles a service principal holds
      effect: read
      questions:
      - Which application permissions has a client app's service principal been granted on other APIs?
      - What app roles does my daemon app hold?
      instructions:
      - text: List the app roles held by client service principal {sp_id}.
        slots:
          sp_id: path.servicePrincipal-id
      - text: Show the application permissions service principal {sp_id} has been granted.
        slots:
          sp_id: path.servicePrincipal-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/servicePrincipals/{servicePrincipal-id}/appRoleAssignments'].post
  update:
    x-apievangelist-phrasing:
      intent: Grant an application permission to a client app
      effect: write
      questions:
      - How do I grant an application permission to a client app's service principal?
      - Can I give my background service an app role on another API?
      instructions:
      - text: Grant client service principal {sp_id} app role {app_role_id} on resource {resource_id}.
        slots:
          sp_id: path.servicePrincipal-id
          app_role_id: requestBody.appRoleId
          resource_id: requestBody.resourceId
      - text: Give app {sp_id} the application permission {app_role_id} from resource {resource_id} as principal {principal_id}.
        slots:
          sp_id: path.servicePrincipal-id
          app_role_id: requestBody.appRoleId
          resource_id: requestBody.resourceId
          principal_id: requestBody.principalId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/servicePrincipals/{servicePrincipal-id}/appRoleAssignments/{appRoleAssignment-id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an app role held by a service principal
      effect: read
      questions:
      - Which resource and permission does one of my client app's role assignments point to?
      - Can I read a single application permission grant my service principal holds?
      instructions:
      - text: Get app role assignment {assignment_id} held by client service principal {sp_id}.
        slots:
          assignment_id: path.appRoleAssignment-id
          sp_id: path.servicePrincipal-id
      - text: Show the resource and permission behind grant {assignment_id} that app {sp_id} holds.
        slots:
          assignment_id: path.appRoleAssignment-id
          sp_id: path.servicePrincipal-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/servicePrincipals/{servicePrincipal-id}/appRoleAssignments/{appRoleAssignment-id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Revoke an application permission from a client app
      effect: destructive
      questions:
      - How do I take an application permission away from a client app's service principal?
      - Can I revoke an app-only permission my daemon was granted?
      instructions:
      - text: Revoke app role assignment {assignment_id} held by client service principal {sp_id}.
        slots:
          assignment_id: path.appRoleAssignment-id
          sp_id: path.servicePrincipal-id
      - text: Remove application permission {assignment_id} from app {sp_id}.
        slots:
          assignment_id: path.appRoleAssignment-id
          sp_id: path.servicePrincipal-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/servicePrincipals/{servicePrincipal-id}/appRoleAssignments/{appRoleAssignment-id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update an app role held by a service principal
      effect: write
      questions:
      - Can I change an application permission grant my client app already holds?
      - Is there a way to edit one of a service principal's own app role assignments?
      instructions:
      - text: Change the role of assignment {assignment_id} held by client app {sp_id} to {app_role_id}.
        slots:
          assignment_id: path.appRoleAssignment-id
          sp_id: path.servicePrincipal-id
          app_role_id: requestBody.appRoleId
      - text: Update the appRoleAssignments entry {assignment_id} of service principal {sp_id}.
        slots:
          assignment_id: path.appRoleAssignment-id
          sp_id: path.servicePrincipal-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/servicePrincipals/{servicePrincipal-id}/appRoleAssignments/$count'].get
  update:
    x-apievangelist-phrasing:
      intent: Count app roles a service principal holds
      effect: read
      questions:
      - How many application permissions has my client app been granted?
      - What's the number of app roles this service principal holds on other resources?
      instructions:
      - text: Count the app roles held by client service principal {sp_id}.
        slots:
          sp_id: path.servicePrincipal-id
      - text: Tell me how many application permissions app {sp_id} has.
        slots:
          sp_id: path.servicePrincipal-id
      method: generated
      generated: '2026-10-01'