# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Auth0 Management Guardian API
  version: 1.0.0
extends: openapi/auth0-guardian-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: 36
- target: $.paths['/guardian/enrollments/ticket'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an MFA enrollment ticket for a user
      effect: write
      questions:
      - How do I send a user a link to enroll in multi-factor authentication?
      - Can an MFA enrollment ticket be emailed to the user automatically in their own language?
      - Is it possible to let a user enroll more than one MFA factor from a single ticket?
      instructions:
      - text: Create an MFA enrollment ticket for user {user_id}.
        slots:
          user_id: requestBody.user_id
      - text: Generate an MFA enrollment ticket for {user_id} and email it to {email}.
        slots:
          user_id: requestBody.user_id
          email: requestBody.email
      - text: Create an enrollment ticket for {user_id} that sets up the {factor} factor.
        slots:
          user_id: requestBody.user_id
          factor: requestBody.factor
      method: generated
      generated: '2026-10-01'
- target: $.paths['/guardian/enrollments/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one MFA enrollment's status and type
      effect: read
      questions:
      - What status and factor type does a specific MFA enrollment have?
      - Can I look up a single multi-factor enrollment by its ID to see if it is confirmed?
      instructions:
      - text: Show me the details of MFA enrollment {id}.
        slots:
          id: path.id
      - text: Check whether MFA enrollment {id} is confirmed.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/guardian/enrollments/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove an MFA enrollment so the user can re-enroll
      effect: destructive
      questions:
      - How do I reset a user's MFA so they can enroll a new device?
      - What happens to a user when I delete one of their MFA enrollments?
      instructions:
      - text: Delete MFA enrollment {id} so the user can enroll again.
        slots:
          id: path.id
      - text: Remove the lost-phone MFA enrollment {id} from the user's account.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/guardian/factors'].get
  update:
    x-apievangelist-phrasing:
      intent: List the tenant's MFA factors
      effect: read
      questions:
      - Which multi-factor authentication factors are available in my Auth0 tenant?
      - Can I see at a glance which MFA factors are turned on or off?
      instructions:
      - text: List every MFA factor in my tenant with its enabled state.
      - text: Show me which MFA factors are currently enabled.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/guardian/factors/duo/settings'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the DUO MFA configuration
      effect: read
      questions:
      - What DUO integration key and API host is my MFA currently set up with?
      - Where can I check the current DUO factor configuration?
      instructions:
      - text: Show me the current DUO MFA configuration.
      - text: Fetch the DUO account settings used for multi-factor authentication.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/guardian/factors/duo/settings'].put
  update:
    x-apievangelist-phrasing:
      intent: Set the full DUO MFA configuration
      effect: write
      questions:
      - How do I connect my DUO account to multi-factor authentication from scratch?
      - Can I replace the whole DUO configuration with new integration and secret keys at once?
      instructions:
      - text: Set the DUO configuration with integration key {ikey}, secret key {skey} and API host {host}.
        slots:
          ikey: requestBody.ikey
          skey: requestBody.skey
          host: requestBody.host
      - text: Replace the entire DUO MFA setup using API host {host}.
        slots:
          host: requestBody.host
      method: generated
      generated: '2026-10-01'
- target: $.paths['/guardian/factors/duo/settings'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change individual DUO MFA settings
      effect: write
      questions:
      - Can I change just the DUO API hostname without re-entering the other keys?
      - How would I rotate only the DUO secret key on an existing setup?
      instructions:
      - text: Update only the DUO secret key to {skey}.
        slots:
          skey: requestBody.skey
      - text: Patch the existing DUO setup to point at API host {host}.
        slots:
          host: requestBody.host
      method: generated
      generated: '2026-10-01'
- target: $.paths['/guardian/factors/phone/message-types'].get
  update:
    x-apievangelist-phrasing:
      intent: List enabled phone MFA delivery methods
      effect: read
      questions:
      - Are SMS codes, voice calls or both enabled for phone MFA?
      - Which phone message types can users receive MFA codes through right now?
      instructions:
      - text: Show me which phone MFA message types are enabled.
      - text: Check whether voice is enabled alongside SMS for phone MFA.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/guardian/factors/phone/message-types'].put
  update:
    x-apievangelist-phrasing:
      intent: Choose SMS and/or voice for phone MFA
      effect: write
      questions:
      - How do I let users get their MFA code by voice call as well as text message?
      - Can I switch phone MFA to SMS only?
      instructions:
      - text: Set the phone MFA message types to {message_types}.
        slots:
          message_types: requestBody.message_types
      - text: Enable both SMS and voice for phone MFA by setting message types to {message_types}.
        slots:
          message_types: requestBody.message_types
      method: generated
      generated: '2026-10-01'
- target: $.paths['/guardian/factors/phone/providers/twilio'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the Twilio phone MFA provider configuration
      effect: read
      questions:
      - Which Twilio sender number and messaging service is my phone MFA using?
      - Where do I view the Twilio settings for phone-based multi-factor authentication?
      instructions:
      - text: Show me the Twilio configuration for phone MFA.
      - text: Fetch the Twilio account SID and from-number configured for phone factors.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/guardian/factors/phone/providers/twilio'].put
  update:
    x-apievangelist-phrasing:
      intent: Update the Twilio phone MFA provider configuration
      effect: write
      questions:
      - How do I change the Twilio number that sends phone MFA codes?
      - Can I switch phone MFA to use a Twilio messaging service SID instead of a from-number?
      instructions:
      - text: Set the Twilio phone provider to send from {from} using account SID {sid}.
        slots:
          from: requestBody.from
          sid: requestBody.sid
      - text: Configure phone MFA Twilio with messaging service {messaging_service_sid} and auth token {auth_token}.
        slots:
          messaging_service_sid: requestBody.messaging_service_sid
          auth_token: requestBody.auth_token
      method: generated
      generated: '2026-10-01'
- target: $.paths['/guardian/factors/phone/selected-provider'].get
  update:
    x-apievangelist-phrasing:
      intent: See which phone provider delivers MFA codes
      effect: read
      questions:
      - Which provider is currently selected for sending phone MFA messages?
      - Is my tenant using Twilio or the built-in phone provider for MFA?
      instructions:
      - text: Show me the selected phone provider for MFA.
      - text: Tell me which phone messaging provider multi-factor authentication currently uses.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/guardian/factors/phone/selected-provider'].put
  update:
    x-apievangelist-phrasing:
      intent: Choose the phone provider for MFA messages
      effect: write
      questions:
      - How do I switch the provider that sends phone MFA codes?
      - Can phone MFA be moved to Twilio as the selected provider?
      instructions:
      - text: Set the phone MFA provider to {provider}.
        slots:
          provider: requestBody.provider
      - text: Switch phone-based multi-factor messaging over to {provider}.
        slots:
          provider: requestBody.provider
      method: generated
      generated: '2026-10-01'
- target: $.paths['/guardian/factors/phone/templates'].get
  update:
    x-apievangelist-phrasing:
      intent: Get phone MFA enrollment and verification messages
      effect: read
      questions:
      - What text do users receive by phone when they enroll in or verify MFA?
      - Where can I read the current phone enrollment and verification message templates?
      instructions:
      - text: Show me the phone MFA enrollment and verification templates.
      - text: Fetch the message text sent by phone for MFA verification codes.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/guardian/factors/phone/templates'].put
  update:
    x-apievangelist-phrasing:
      intent: Customize phone MFA enrollment and verification messages
      effect: write
      questions:
      - Can I rewrite the text message users get when verifying MFA by phone?
      - How do I brand the phone enrollment message for multi-factor authentication?
      instructions:
      - text: Set the phone enrollment message to {enrollment_message} and the verification message to {verification_message}.
        slots:
          enrollment_message: requestBody.enrollment_message
          verification_message: requestBody.verification_message
      - text: Update the phone factor templates with verification text {verification_message} and enrollment text {enrollment_message}.
        slots:
          verification_message: requestBody.verification_message
          enrollment_message: requestBody.enrollment_message
      method: generated
      generated: '2026-10-01'
- target: $.paths['/guardian/factors/push-notification/providers/apns'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the APNs push MFA configuration
      effect: read
      questions:
      - Which iOS bundle ID is set for push notification MFA through APNs?
      - Is my APNs push configuration in sandbox or production mode?
      instructions:
      - text: Show me the APNs push notification configuration for MFA.
      - text: Check whether the APNs MFA provider is set to sandbox.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/guardian/factors/push-notification/providers/apns'].put
  update:
    x-apievangelist-phrasing:
      intent: Overwrite the APNs push MFA configuration
      effect: write
      questions:
      - How do I set up APNs from scratch for push-based MFA on iOS?
      - Can I replace the whole APNs configuration with a new p12 certificate and bundle ID?
      instructions:
      - text: Replace the APNs configuration with bundle ID {bundle_id} and certificate {p12}.
        slots:
          bundle_id: requestBody.bundle_id
          p12: requestBody.p12
      - text: Overwrite all APNs push settings using bundle {bundle_id} in sandbox mode {sandbox}.
        slots:
          bundle_id: requestBody.bundle_id
          sandbox: requestBody.sandbox
      method: generated
      generated: '2026-10-01'
- target: $.paths['/guardian/factors/push-notification/providers/apns'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change individual APNs push MFA settings
      effect: write
      questions:
      - Can I flip APNs from sandbox to production without re-uploading the certificate?
      - How do I swap just the APNs p12 certificate when it expires?
      instructions:
      - text: Update only the APNs sandbox flag to {sandbox}.
        slots:
          sandbox: requestBody.sandbox
      - text: Patch the existing APNs setup with renewed certificate {p12}.
        slots:
          p12: requestBody.p12
      method: generated
      generated: '2026-10-01'
- target: $.paths['/guardian/factors/push-notification/providers/fcm'].put
  update:
    x-apievangelist-phrasing:
      intent: Overwrite the legacy FCM push MFA configuration
      effect: write
      questions:
      - How do I set the legacy FCM server key for Android push MFA from scratch?
      - Can I replace the whole legacy FCM configuration in one call?
      instructions:
      - text: Replace the legacy FCM push configuration with server key {server_key}.
        slots:
          server_key: requestBody.server_key
      - text: Overwrite all FCM (legacy) settings for MFA push using key {server_key}.
        slots:
          server_key: requestBody.server_key
      method: generated
      generated: '2026-10-01'
- target: $.paths['/guardian/factors/push-notification/providers/fcm'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update the legacy FCM server key for push MFA
      effect: write
      questions:
      - Can I rotate just the legacy FCM server key on my existing push MFA setup?
      - Is there a partial update for the older FCM provider configuration?
      instructions:
      - text: Patch the legacy FCM provider with new server key {server_key}.
        slots:
          server_key: requestBody.server_key
      - text: Rotate the legacy FCM server key to {server_key} without resetting other settings.
        slots:
          server_key: requestBody.server_key
      method: generated
      generated: '2026-10-01'
- target: $.paths['/guardian/factors/push-notification/providers/fcmv1'].put
  update:
    x-apievangelist-phrasing:
      intent: Overwrite the FCM v1 push MFA configuration
      effect: write
      questions:
      - How do I configure FCM HTTP v1 service account credentials for Android push MFA?
      - Can I replace the full FCMv1 configuration with a new service account JSON?
      instructions:
      - text: Replace the FCMv1 push configuration with credentials {server_credentials}.
        slots:
          server_credentials: requestBody.server_credentials
      - text: Overwrite all FCM v1 settings for push MFA using service account {server_credentials}.
        slots:
          server_credentials: requestBody.server_credentials
      method: generated
      generated: '2026-10-01'
- target: $.paths['/guardian/factors/push-notification/providers/fcmv1'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update the FCM v1 push MFA credentials
      effect: write
      questions:
      - Can I rotate just the FCMv1 service account credentials on an existing push setup?
      - Is there a partial update for the FCM v1 provider used by Guardian push?
      instructions:
      - text: Patch the FCMv1 provider with new credentials {server_credentials}.
        slots:
          server_credentials: requestBody.server_credentials
      - text: Rotate the FCM v1 service account to {server_credentials} without resetting other settings.
        slots:
          server_credentials: requestBody.server_credentials
      method: generated
      generated: '2026-10-01'
- target: $.paths['/guardian/factors/push-notification/providers/sns'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the AWS SNS push MFA configuration
      effect: read
      questions:
      - Which AWS region and platform application ARNs is push MFA using via SNS?
      - Where can I view my AWS SNS push notification settings for MFA?
      instructions:
      - text: Show me the AWS SNS push notification configuration for MFA.
      - text: Fetch the SNS APNs and GCM platform application ARNs used for push MFA.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/guardian/factors/push-notification/providers/sns'].put
  update:
    x-apievangelist-phrasing:
      intent: Configure AWS SNS for push MFA from scratch
      effect: write
      questions:
      - How do I route push MFA notifications through my own AWS SNS account?
      - Can I replace the whole SNS push configuration with new AWS keys and region?
      instructions:
      - text: Configure SNS push MFA in region {aws_region} with access key {aws_access_key_id} and secret {aws_secret_access_key}.
        slots:
          aws_region: requestBody.aws_region
          aws_access_key_id: requestBody.aws_access_key_id
          aws_secret_access_key: requestBody.aws_secret_access_key
      - text: Replace the SNS setup with APNs platform ARN {sns_apns_platform_application_arn}.
        slots:
          sns_apns_platform_application_arn: requestBody.sns_apns_platform_application_arn
      method: generated
      generated: '2026-10-01'
- target: $.paths['/guardian/factors/push-notification/providers/sns'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change individual AWS SNS push MFA settings
      effect: write
      questions:
      - Can I update only the GCM platform ARN in my existing SNS push setup?
      - How would I rotate just the AWS secret key used for SNS push MFA?
      instructions:
      - text: Patch the SNS push setup with GCM platform ARN {sns_gcm_platform_application_arn}.
        slots:
          sns_gcm_platform_application_arn: requestBody.sns_gcm_platform_application_arn
      - text: Update only the SNS AWS secret key to {aws_secret_access_key}.
        slots:
          aws_secret_access_key: requestBody.aws_secret_access_key
      method: generated
      generated: '2026-10-01'
- target: $.paths['/guardian/factors/push-notification/selected-provider'].get
  update:
    x-apievangelist-phrasing:
      intent: See which push notification provider MFA uses
      effect: read
      questions:
      - Is push MFA currently delivered through Guardian, SNS or direct APNs/FCM?
      - Which push notification provider is selected for my tenant?
      instructions:
      - text: Show me the selected push notification provider for MFA.
      - text: Tell me which provider sends Guardian push notifications.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/guardian/factors/push-notification/selected-provider'].put
  update:
    x-apievangelist-phrasing:
      intent: Choose the push notification provider for MFA
      effect: write
      questions:
      - How do I switch push MFA to deliver through AWS SNS?
      - Can I change the selected push notification provider for Guardian?
      instructions:
      - text: Set the push notification provider for MFA to {provider}.
        slots:
          provider: requestBody.provider
      - text: Switch Guardian push delivery over to {provider}.
        slots:
          provider: requestBody.provider
      method: generated
      generated: '2026-10-01'
- target: $.paths['/guardian/factors/sms/providers/twilio'].get
  update:
    x-apievangelist-phrasing:
      intent: Get Twilio SMS MFA settings (deprecated endpoint)
      effect: read
      questions:
      - What does the older SMS-only Twilio configuration endpoint return?
      - Can I still read Twilio settings through the deprecated SMS factor path?
      instructions:
      - text: Fetch the Twilio configuration from the deprecated SMS factor endpoint.
      - text: Show me the legacy SMS-factor Twilio settings.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/guardian/factors/sms/providers/twilio'].put
  update:
    x-apievangelist-phrasing:
      intent: Update Twilio SMS MFA settings (deprecated endpoint)
      effect: write
      questions:
      - Does the deprecated SMS Twilio endpoint still accept a new from-number?
      - What fields does the older SMS-only Twilio update take?
      instructions:
      - text: Using the deprecated SMS endpoint, set the Twilio from-number to {from}.
        slots:
          from: requestBody.from
      - text: Update the legacy SMS Twilio config with SID {sid} and auth token {auth_token}.
        slots:
          sid: requestBody.sid
          auth_token: requestBody.auth_token
      method: generated
      generated: '2026-10-01'
- target: $.paths['/guardian/factors/sms/selected-provider'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the SMS MFA provider (deprecated endpoint)
      effect: read
      questions:
      - Which provider does the old SMS selected-provider endpoint report?
      - Can I still check the SMS provider via the deprecated SMS path?
      instructions:
      - text: Read the selected SMS provider from the deprecated SMS endpoint.
      - text: Show me the legacy SMS-factor provider selection.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/guardian/factors/sms/selected-provider'].put
  update:
    x-apievangelist-phrasing:
      intent: Set the SMS MFA provider (deprecated endpoint)
      effect: write
      questions:
      - Does the deprecated SMS selected-provider endpoint still let me pick a provider?
      - What value does the legacy SMS provider update expect?
      instructions:
      - text: Using the deprecated SMS endpoint, set the SMS provider to {provider}.
        slots:
          provider: requestBody.provider
      - text: Switch the legacy SMS-factor provider to {provider}.
        slots:
          provider: requestBody.provider
      method: generated
      generated: '2026-10-01'
- target: $.paths['/guardian/factors/sms/templates'].get
  update:
    x-apievangelist-phrasing:
      intent: Get SMS MFA message templates (deprecated endpoint)
      effect: read
      questions:
      - What do the old SMS-only enrollment and verification templates say?
      - Can I still read SMS templates through the deprecated SMS factor path?
      instructions:
      - text: Fetch the SMS enrollment and verification templates from the deprecated endpoint.
      - text: Show me the legacy SMS-factor message templates.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/guardian/factors/sms/templates'].put
  update:
    x-apievangelist-phrasing:
      intent: Update SMS MFA message templates (deprecated endpoint)
      effect: write
      questions:
      - Does the deprecated SMS templates endpoint still let me change the message text?
      - Which two messages must I send to the legacy SMS template update?
      instructions:
      - text: Using the deprecated SMS endpoint, set enrollment text {enrollment_message} and verification text {verification_message}.
        slots:
          enrollment_message: requestBody.enrollment_message
          verification_message: requestBody.verification_message
      - text: Update the legacy SMS templates so verification reads {verification_message} and enrollment reads {enrollment_message}.
        slots:
          verification_message: requestBody.verification_message
          enrollment_message: requestBody.enrollment_message
      method: generated
      generated: '2026-10-01'
- target: $.paths['/guardian/factors/{name}'].put
  update:
    x-apievangelist-phrasing:
      intent: Turn an MFA factor on or off
      effect: write
      questions:
      - How do I enable one-time password MFA for my tenant?
      - Can I disable a single MFA factor like email without touching the others?
      instructions:
      - text: Enable the {name} MFA factor by setting enabled to {enabled}.
        slots:
          name: path.name
          enabled: requestBody.enabled
      - text: Turn off the {name} factor (enabled {enabled}).
        slots:
          name: path.name
          enabled: requestBody.enabled
      method: generated
      generated: '2026-10-01'
- target: $.paths['/guardian/policies'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the tenant's MFA policies
      effect: read
      questions:
      - Is MFA required on every login or only when confidence is low?
      - What multi-factor authentication policy is my tenant enforcing today?
      instructions:
      - text: Show me the MFA policies configured for my tenant.
      - text: Tell me whether all-applications MFA is enforced.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/guardian/policies'].put
  update:
    x-apievangelist-phrasing:
      intent: Set the tenant's MFA policies
      effect: write
      questions:
      - How do I require MFA for every application in my tenant?
      - Can I switch to confidence-score based MFA instead of always prompting?
      instructions:
      - text: Set the MFA policy to require multi-factor on all applications.
      - text: Replace the tenant MFA policies with the confidence-score policy.
      method: generated
      generated: '2026-10-01'