# 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 Users API
  version: 1.0.0
extends: openapi/auth0-users-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: 37
- target: $.paths['/users'].get
  update:
    x-apievangelist-phrasing:
      intent: List or search users in a tenant
      effect: read
      questions:
      - How do I search my Auth0 users by email or a metadata field?
      - Can I sort the user list and page through it a few dozen at a time?
      - Which users signed up through a specific connection?
      instructions:
      - text: Search users matching {q}.
        slots:
          q: query.q
      - text: List users from the {connection} connection, {per_page} per page.
        slots:
          connection: query.connection
          per_page: query.per_page
      - text: List all users sorted by {sort}.
        slots:
          sort: query.sort
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a user in a connection
      effect: write
      questions:
      - How do I add a new user to a database connection?
      - Can I create a user and set their password and metadata at the same time?
      - Is it possible to create a user who still needs to verify their email?
      instructions:
      - text: Create a user {email} in the {connection} connection.
        slots:
          email: requestBody.email
          connection: requestBody.connection
      - text: Create user {email} in {connection} with password {password}.
        slots:
          email: requestBody.email
          connection: requestBody.connection
          password: requestBody.password
      - text: Add a passwordless user with phone {phone_number} to {connection}.
        slots:
          phone_number: requestBody.phone_number
          connection: requestBody.connection
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user's profile by ID
      effect: read
      questions:
      - What does the full profile of a single user look like by user ID?
      - Can I fetch only certain fields of one user's profile?
      instructions:
      - text: Show me the profile for user {id}.
        slots:
          id: path.id
      - text: Get only the {fields} fields of user {id}.
        slots:
          fields: query.fields
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a user permanently
      effect: destructive
      questions:
      - How do I permanently delete a user account?
      - Is deleting a user reversible once it's done?
      instructions:
      - text: Delete user {id} permanently.
        slots:
          id: path.id
      - text: Remove the account of user {id} from the tenant.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a user's profile
      effect: write
      questions:
      - Can I change a user's email address or block their account?
      - How do I update a user's app_metadata or user_metadata?
      - Is it possible to reset a user's password directly from the management side?
      instructions:
      - text: Block user {id}.
        slots:
          id: path.id
      - text: Change the email of user {id} to {email}.
        slots:
          id: path.id
          email: requestBody.email
      - text: Set a new password {password} for user {id}.
        slots:
          password: requestBody.password
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}/authentication-methods'].get
  update:
    x-apievangelist-phrasing:
      intent: List a user's authentication methods
      effect: read
      questions:
      - Which MFA authentication methods has a user enrolled?
      - Can I see every authentication method attached to one user?
      instructions:
      - text: List the authentication methods of user {id}.
        slots:
          id: path.id
      - text: Show all enrolled factors for user {id} with totals.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}/authentication-methods'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace all of a user's authentication methods
      effect: write
      questions:
      - Can I overwrite a user's whole set of authentication methods in one call?
      - What happens to existing factors when I replace a user's authentication methods?
      instructions:
      - text: Replace every authentication method of user {id} with a new set.
        slots:
          id: path.id
      - text: Overwrite user {id}'s enrolled factors with the ones I provide.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}/authentication-methods'].post
  update:
    x-apievangelist-phrasing:
      intent: Add an authentication method to a user
      effect: write
      questions:
      - How do I enroll a phone or TOTP factor for a user on their behalf?
      - Can I add a pre-verified authentication method to a user account?
      instructions:
      - text: Add a {type} authentication method to user {id}.
        slots:
          type: requestBody.type
          id: path.id
      - text: Enroll phone {phone_number} as an SMS factor for user {id} as type {type}.
        slots:
          phone_number: requestBody.phone_number
          id: path.id
          type: requestBody.type
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}/authentication-methods'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove all of a user's authentication methods
      effect: destructive
      questions:
      - How do I wipe every MFA factor a user has enrolled?
      - Can I clear all authentication methods for a locked-out user?
      instructions:
      - text: Remove all authentication methods from user {id}.
        slots:
          id: path.id
      - text: Clear every enrolled MFA factor on user {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}/authentication-methods/{authentication_method_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one authentication method of a user
      effect: read
      questions:
      - Can I look up the details of one specific authentication method on a user?
      - What information is stored for a single enrolled factor?
      instructions:
      - text: Show authentication method {authentication_method_id} of user {id}.
        slots:
          authentication_method_id: path.authentication_method_id
          id: path.id
      - text: Get the details of factor {authentication_method_id} for user {id}.
        slots:
          authentication_method_id: path.authentication_method_id
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}/authentication-methods/{authentication_method_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove one authentication method from a user
      effect: destructive
      questions:
      - How do I remove just one enrolled factor from a user and keep the rest?
      - Can I delete a single lost phone factor from someone's account?
      instructions:
      - text: Delete authentication method {authentication_method_id} from user {id}.
        slots:
          authentication_method_id: path.authentication_method_id
          id: path.id
      - text: Remove only factor {authentication_method_id} on user {id}.
        slots:
          authentication_method_id: path.authentication_method_id
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}/authentication-methods/{authentication_method_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Rename or prefer a user's authentication method
      effect: write
      questions:
      - Can I rename a user's authentication method or make it their preferred one?
      - How do I change which enrolled factor a user is prompted with first?
      instructions:
      - text: Rename authentication method {authentication_method_id} of user {id} to {name}.
        slots:
          authentication_method_id: path.authentication_method_id
          id: path.id
          name: requestBody.name
      - text: Set the preferred method of factor {authentication_method_id} for user {id} to {preferred_authentication_method}.
        slots:
          authentication_method_id: path.authentication_method_id
          id: path.id
          preferred_authentication_method: requestBody.preferred_authentication_method
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}/authenticators'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove all authenticators from a user
      effect: destructive
      questions:
      - Can I delete every authenticator a user registered, like OTP, push and email?
      - What's the way to reset all of a user's MFA authenticators at once?
      instructions:
      - text: Delete all authenticators registered to user {id}.
        slots:
          id: path.id
      - text: Reset user {id}'s OTP, push, email and phone authenticators.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}/connected-accounts'].get
  update:
    x-apievangelist-phrasing:
      intent: List a user's connected accounts
      effect: read
      questions:
      - Which connected accounts are linked to a user?
      - Can I page through a user's connected accounts with a checkpoint?
      instructions:
      - text: List connected accounts for user {id}.
        slots:
          id: path.id
      - text: Show {take} connected accounts of user {id} starting from {from}.
        slots:
          take: query.take
          id: path.id
          from: query.from
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}/enrollments'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user's first confirmed MFA enrollment
      effect: read
      questions:
      - Has this user confirmed an MFA enrollment yet?
      - What is the first multi-factor enrollment a user completed?
      instructions:
      - text: Get the first confirmed MFA enrollment of user {id}.
        slots:
          id: path.id
      - text: Check whether user {id} has finished MFA enrollment.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}/federated-connections-tokensets'].get
  update:
    x-apievangelist-phrasing:
      intent: List a user's federated connection tokensets
      effect: read
      questions:
      - Which federated connection tokensets are active for a user?
      - Can I see the token sets stored for a user's federated connections?
      instructions:
      - text: List active federated tokensets for user {id}.
        slots:
          id: path.id
      - text: Show the federated connection token sets held for user {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}/federated-connections-tokensets/{tokenset_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a user's federated connection tokenset
      effect: destructive
      questions:
      - How do I revoke one federated connection tokenset for a user?
      - Can I delete a stored token set from a user's federated connection?
      instructions:
      - text: Delete tokenset {tokenset_id} of user {id}.
        slots:
          tokenset_id: path.tokenset_id
          id: path.id
      - text: Remove federated token set {tokenset_id} from user {id}.
        slots:
          tokenset_id: path.tokenset_id
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}/groups'].get
  update:
    x-apievangelist-phrasing:
      intent: List the groups a user belongs to
      effect: read
      questions:
      - Which groups is a given user a member of?
      - Can I list a user's group memberships page by page?
      instructions:
      - text: List the groups user {id} belongs to.
        slots:
          id: path.id
      - text: Show {per_page} groups per page for user {id}.
        slots:
          per_page: query.per_page
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}/identities'].post
  update:
    x-apievangelist-phrasing:
      intent: Link a secondary account to a user
      effect: write
      questions:
      - How do I merge a social login account into a user's primary account?
      - Can I link two user accounts so one becomes the primary identity?
      instructions:
      - text: Link user {user_id} from {provider} to primary user {id}.
        slots:
          user_id: requestBody.user_id
          provider: requestBody.provider
          id: path.id
      - text: Link the account in token {link_with} to user {id}.
        slots:
          link_with: requestBody.link_with
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}/identities/{provider}/{user_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Unlink a secondary identity from a user
      effect: destructive
      questions:
      - Can I split a linked social identity back out of a primary account?
      - What do I need to unlink a secondary account from a user?
      instructions:
      - text: Unlink the {provider} identity {user_id} from user {id}.
        slots:
          provider: path.provider
          user_id: path.user_id
          id: path.id
      - text: Separate secondary account {user_id} ({provider}) from primary user {id}.
        slots:
          user_id: path.user_id
          provider: path.provider
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}/logs'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user's log events
      effect: read
      questions:
      - What login and activity events were logged for one user?
      - Can I sort a single user's log events by date?
      instructions:
      - text: Show log events for user {id}.
        slots:
          id: path.id
      - text: List user {id}'s log events sorted by {sort}.
        slots:
          id: path.id
          sort: query.sort
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}/multifactor/actions/invalidate-remember-browser'].post
  update:
    x-apievangelist-phrasing:
      intent: Forget a user's remembered MFA browsers
      effect: write
      questions:
      - How do I force a user to do MFA again on browsers they told us to remember?
      - Can I invalidate all remembered browsers for a user's MFA?
      instructions:
      - text: Invalidate all remembered MFA browsers for user {id}.
        slots:
          id: path.id
      - text: Make user {id} pass MFA again on every browser.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}/multifactor/{provider}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a user's multifactor provider
      effect: destructive
      questions:
      - Can I remove a specific multifactor provider like Duo from a user's account?
      - Will removing a user's MFA provider make them set it up again?
      instructions:
      - text: Remove the {provider} multifactor provider from user {id}.
        slots:
          provider: path.provider
          id: path.id
      - text: Delete user {id}'s {provider} MFA configuration.
        slots:
          id: path.id
          provider: path.provider
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}/organizations'].get
  update:
    x-apievangelist-phrasing:
      intent: List a user's organization memberships
      effect: read
      questions:
      - Which organizations does a user currently belong to?
      - Can I count how many organizations a user is a member of?
      instructions:
      - text: List organizations for user {id}.
        slots:
          id: path.id
      - text: Show organization memberships of user {id} with totals.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}/permissions'].get
  update:
    x-apievangelist-phrasing:
      intent: List a user's direct permissions
      effect: read
      questions:
      - Which API permissions are assigned to a user?
      - Can I page through all permissions a user holds?
      instructions:
      - text: List permissions of user {id}.
        slots:
          id: path.id
      - text: Show page {page} of user {id}'s permissions.
        slots:
          page: query.page
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}/permissions'].post
  update:
    x-apievangelist-phrasing:
      intent: Assign permissions to a user
      effect: write
      questions:
      - How do I grant API permissions directly to a user without a role?
      - Can I give a user several permissions in one request?
      instructions:
      - text: Assign permissions {permissions} to user {id}.
        slots:
          permissions: requestBody.permissions
          id: path.id
      - text: Grant user {id} the scopes {permissions}.
        slots:
          id: path.id
          permissions: requestBody.permissions
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}/permissions'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove permissions from a user
      effect: destructive
      questions:
      - How do I take a permission away from a user?
      - Can I revoke several directly assigned permissions from one user?
      instructions:
      - text: Remove permissions {permissions} from user {id}.
        slots:
          permissions: requestBody.permissions
          id: path.id
      - text: Revoke the scopes {permissions} held by user {id}.
        slots:
          permissions: requestBody.permissions
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}/recovery-code-regeneration'].post
  update:
    x-apievangelist-phrasing:
      intent: Regenerate a user's MFA recovery code
      effect: write
      questions:
      - A user lost their MFA recovery code, can I issue a new one?
      - What happens to the old recovery code when I generate a new one?
      instructions:
      - text: Generate a new MFA recovery code for user {id}.
        slots:
          id: path.id
      - text: Replace user {id}'s recovery code.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}/revoke-access'].post
  update:
    x-apievangelist-phrasing:
      intent: Revoke a user's sessions and tokens
      effect: destructive
      questions:
      - How do I sign a user out of everything by revoking their sessions and refresh tokens?
      - Can I revoke one session for a user but keep their refresh tokens?
      instructions:
      - text: Revoke access for user {id}.
        slots:
          id: path.id
      - text: Revoke session {session_id} for user {id}.
        slots:
          session_id: requestBody.session_id
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}/risk-assessments/clear'].post
  update:
    x-apievangelist-phrasing:
      intent: Clear risk assessors for a user
      effect: write
      questions:
      - Can I reset the risk assessment data kept for a user, like known devices?
      - How do I clear risk assessors on one connection for a specific user?
      instructions:
      - text: Clear risk assessors {assessors} for user {id} on {connection}.
        slots:
          assessors: requestBody.assessors
          id: path.id
          connection: requestBody.connection
      - text: Reset the {assessors} risk assessment for user {id} in connection {connection}.
        slots:
          assessors: requestBody.assessors
          id: path.id
          connection: requestBody.connection
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}/roles'].get
  update:
    x-apievangelist-phrasing:
      intent: List a user's roles
      effect: read
      questions:
      - Which roles are assigned to a user across the whole tenant?
      - Can I page through all roles given to one user?
      instructions:
      - text: List roles assigned to user {id}.
        slots:
          id: path.id
      - text: Show {per_page} of user {id}'s roles per page.
        slots:
          per_page: query.per_page
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}/roles'].post
  update:
    x-apievangelist-phrasing:
      intent: Assign roles to a user
      effect: write
      questions:
      - How do I give a user an existing role?
      - Can I assign several roles to one user at once?
      instructions:
      - text: Assign roles {roles} to user {id}.
        slots:
          roles: requestBody.roles
          id: path.id
      - text: Give user {id} the roles {roles}.
        slots:
          id: path.id
          roles: requestBody.roles
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}/roles'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove roles from a user
      effect: destructive
      questions:
      - How do I take a role away from a user?
      - Does removing a role from a user apply across the whole tenant?
      instructions:
      - text: Remove roles {roles} from user {id}.
        slots:
          roles: requestBody.roles
          id: path.id
      - text: Unassign role {roles} from user {id}.
        slots:
          roles: requestBody.roles
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user_id}/refresh-tokens'].get
  update:
    x-apievangelist-phrasing:
      intent: List a user's refresh tokens
      effect: read
      questions:
      - Which refresh tokens does a user currently have?
      - Can I see how many refresh tokens were issued to one user?
      instructions:
      - text: List refresh tokens for user {user_id}.
        slots:
          user_id: path.user_id
      - text: Show {take} refresh tokens of user {user_id}.
        slots:
          take: query.take
          user_id: path.user_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user_id}/refresh-tokens'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete all of a user's refresh tokens
      effect: destructive
      questions:
      - How do I revoke every refresh token a user holds?
      - Can I invalidate all refresh tokens for a compromised account?
      instructions:
      - text: Delete all refresh tokens for user {user_id}.
        slots:
          user_id: path.user_id
      - text: Revoke every refresh token issued to user {user_id}.
        slots:
          user_id: path.user_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user_id}/sessions'].get
  update:
    x-apievangelist-phrasing:
      intent: List a user's sessions
      effect: read
      questions:
      - What active sessions does a user have right now?
      - Can I page through a user's login sessions?
      instructions:
      - text: List sessions for user {user_id}.
        slots:
          user_id: path.user_id
      - text: Show {take} sessions of user {user_id} from {from}.
        slots:
          take: query.take
          user_id: path.user_id
          from: query.from
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user_id}/sessions'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete all of a user's sessions
      effect: destructive
      questions:
      - How do I end every session a user has open?
      - Can I log a user out of all devices by deleting their sessions?
      instructions:
      - text: Delete all sessions for user {user_id}.
        slots:
          user_id: path.user_id
      - text: Log user {user_id} out of every session.
        slots:
          user_id: path.user_id
      method: generated
      generated: '2026-10-01'