API Evangelist conversational phrasing for Applications Service Principals.service Principal.Actions…

# 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.service Principal.Actions…
  version: 1.0.0
extends: openapi/azure-ad-serviceprincipals-serviceprincipal-actions-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: 13
- target: $.paths['/servicePrincipals/{servicePrincipal-id}/microsoft.graph.addKey'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a key credential to a service principal
      effect: write
      questions:
      - How do I roll an expiring certificate key on a service principal?
      - Do I need a proof-of-possession token to add a new key to a service principal?
      instructions:
      - text: Add key credential {key_credential} to service principal {service_principal} with proof {proof}.
        slots:
          key_credential: requestBody.keyCredential
          service_principal: path.servicePrincipal-id
          proof: requestBody.proof
      - text: Add a new certificate key to service principal {service_principal}.
        slots:
          service_principal: path.servicePrincipal-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/servicePrincipals/{servicePrincipal-id}/microsoft.graph.addPassword'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a client secret to a service principal
      effect: write
      questions:
      - Can I generate a new client secret for a service principal?
      - What does the API return when I add a password to a service principal?
      instructions:
      - text: Add a new password {password_credential} to service principal {service_principal}.
        slots:
          password_credential: requestBody.passwordCredential
          service_principal: path.servicePrincipal-id
      - text: Generate a strong client secret for service principal {service_principal}.
        slots:
          service_principal: path.servicePrincipal-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/servicePrincipals/{servicePrincipal-id}/microsoft.graph.addTokenSigningCertificate'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a token signing certificate for a service principal
      effect: write
      questions:
      - How do I create a self-signed SAML token signing certificate for an enterprise app?
      - Can I choose the display name and expiry date of a service principal's signing certificate?
      instructions:
      - text: Create a token signing certificate named {display_name} for service principal {service_principal}, expiring {end_date}.
        slots:
          display_name: requestBody.displayName
          service_principal: path.servicePrincipal-id
          end_date: requestBody.endDateTime
      - text: Generate a self-signed signing certificate for service principal {service_principal}.
        slots:
          service_principal: path.servicePrincipal-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/servicePrincipals/{servicePrincipal-id}/microsoft.graph.checkMemberGroups'].post
  update:
    x-apievangelist-phrasing:
      intent: Check a service principal's membership in given groups
      effect: read
      questions:
      - Is a service principal a member of any of these specific groups?
      - Can I check a list of group IDs against a service principal's memberships in one call?
      instructions:
      - text: Check which of groups {group_ids} service principal {service_principal} belongs to.
        slots:
          group_ids: requestBody.groupIds
          service_principal: path.servicePrincipal-id
      - text: Tell me if service principal {service_principal} is in group list {group_ids}.
        slots:
          service_principal: path.servicePrincipal-id
          group_ids: requestBody.groupIds
      method: generated
      generated: '2026-10-01'
- target: $.paths['/servicePrincipals/{servicePrincipal-id}/microsoft.graph.checkMemberObjects'].post
  update:
    x-apievangelist-phrasing:
      intent: Check a service principal's membership in given objects
      effect: read
      questions:
      - Can I test whether a service principal is a member of specific groups, roles or administrative units?
      - Which of a list of directory object IDs does a service principal belong to?
      instructions:
      - text: Check which of objects {ids} service principal {service_principal} is a member of.
        slots:
          ids: requestBody.ids
          service_principal: path.servicePrincipal-id
      - text: Test service principal {service_principal} membership against roles and units {ids}.
        slots:
          service_principal: path.servicePrincipal-id
          ids: requestBody.ids
      method: generated
      generated: '2026-10-01'
- target: $.paths['/servicePrincipals/{servicePrincipal-id}/microsoft.graph.getMemberGroups'].post
  update:
    x-apievangelist-phrasing:
      intent: Get all groups a service principal belongs to
      effect: read
      questions:
      - Which groups is a service principal a member of, including nested ones?
      - Can I restrict a service principal's group memberships to security groups only?
      instructions:
      - text: Get every group ID service principal {service_principal} belongs to.
        slots:
          service_principal: path.servicePrincipal-id
      - text: 'List group memberships for service principal {service_principal}, security groups only: {security_only}.'
        slots:
          service_principal: path.servicePrincipal-id
          security_only: requestBody.securityEnabledOnly
      method: generated
      generated: '2026-10-01'
- target: $.paths['/servicePrincipals/{servicePrincipal-id}/microsoft.graph.getMemberObjects'].post
  update:
    x-apievangelist-phrasing:
      intent: Get all groups, roles and units a service principal is in
      effect: read
      questions:
      - What groups, administrative units and directory roles does a service principal belong to?
      - Can I get every membership object ID for a service principal, not just groups?
      instructions:
      - text: Get all group, role and administrative unit IDs for service principal {service_principal}.
        slots:
          service_principal: path.servicePrincipal-id
      - text: List every membership object of service principal {service_principal} with securityEnabledOnly {security_only}.
        slots:
          service_principal: path.servicePrincipal-id
          security_only: requestBody.securityEnabledOnly
      method: generated
      generated: '2026-10-01'
- target: $.paths['/servicePrincipals/{servicePrincipal-id}/microsoft.graph.removeKey'].post
  update:
    x-apievangelist-phrasing:
      intent: Remove a key credential from a service principal
      effect: destructive
      questions:
      - How do I retire an old certificate key from a service principal?
      - What proof do I need to remove a key credential from a service principal?
      instructions:
      - text: Remove key {key_id} from service principal {service_principal} using proof {proof}.
        slots:
          key_id: requestBody.keyId
          service_principal: path.servicePrincipal-id
          proof: requestBody.proof
      - text: Delete the expiring certificate key {key_id} on service principal {service_principal}.
        slots:
          key_id: requestBody.keyId
          service_principal: path.servicePrincipal-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/servicePrincipals/{servicePrincipal-id}/microsoft.graph.removePassword'].post
  update:
    x-apievangelist-phrasing:
      intent: Remove a client secret from a service principal
      effect: destructive
      questions:
      - Can I revoke a client secret that was added to a service principal?
      - Which ID do I pass to delete a password from a service principal?
      instructions:
      - text: Remove password {key_id} from service principal {service_principal}.
        slots:
          key_id: requestBody.keyId
          service_principal: path.servicePrincipal-id
      - text: Revoke the client secret {key_id} on service principal {service_principal}.
        slots:
          key_id: requestBody.keyId
          service_principal: path.servicePrincipal-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/servicePrincipals/{servicePrincipal-id}/microsoft.graph.restore'].post
  update:
    x-apievangelist-phrasing:
      intent: Restore a deleted service principal
      effect: write
      questions:
      - Can I bring back a service principal that was recently deleted?
      - How long do I have to restore a deleted enterprise app from deleted items?
      instructions:
      - text: Restore deleted service principal {service_principal}.
        slots:
          service_principal: path.servicePrincipal-id
      - text: Recover service principal {service_principal} from deleted items.
        slots:
          service_principal: path.servicePrincipal-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/servicePrincipals/microsoft.graph.getAvailableExtensionProperties'].post
  update:
    x-apievangelist-phrasing:
      intent: List directory extension properties available
      effect: read
      questions:
      - What directory extension attributes are registered in my tenant, including from multitenant apps?
      - Can I see only the extension properties synced from on-premises?
      instructions:
      - text: List all directory extension properties available in the tenant.
      - text: Show available extension properties where synced from on-premises is {synced}.
        slots:
          synced: requestBody.isSyncedFromOnPremises
      method: generated
      generated: '2026-10-01'
- target: $.paths['/servicePrincipals/microsoft.graph.getByIds'].post
  update:
    x-apievangelist-phrasing:
      intent: Look up directory objects by a list of IDs
      effect: read
      questions:
      - Can I resolve a batch of object IDs to users, groups and service principals in one request?
      - Is it possible to limit an ID lookup to certain object types?
      instructions:
      - text: Look up the directory objects with IDs {ids}.
        slots:
          ids: requestBody.ids
      - text: Resolve IDs {ids} to objects of types {types}.
        slots:
          ids: requestBody.ids
          types: requestBody.types
      method: generated
      generated: '2026-10-01'
- target: $.paths['/servicePrincipals/microsoft.graph.validateProperties'].post
  update:
    x-apievangelist-phrasing:
      intent: Check a group name against naming policy
      effect: read
      questions:
      - Will a Microsoft 365 group display name pass my tenant's naming policy before I create it?
      - Can I check whether a mail nickname contains blocked words?
      instructions:
      - text: Validate display name {display_name} and mail nickname {mail_nickname} for a {entity_type}.
        slots:
          display_name: requestBody.displayName
          mail_nickname: requestBody.mailNickname
          entity_type: requestBody.entityType
      - text: Check group name {display_name} against naming policy on behalf of user {user}.
        slots:
          display_name: requestBody.displayName
          user: requestBody.onBehalfOfUserId
      method: generated
      generated: '2026-10-01'