API Evangelist conversational phrasing for Tenable Platform & Settings Access Control (Users) API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Tenable Platform & Settings Access Control (Users) API
  version: 1.0.0
extends: openapi/tenable-access-control-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: 15
- target: $.paths['/users'].get
  update:
    x-apievangelist-phrasing:
      intent: List users in the workspace
      effect: read
      questions:
      - Who has a user account in my Tenable Vulnerability Management instance?
      - Can I see each user's role alongside the user list?
      instructions:
      - text: List every user account in the workspace.
      - text: List all users and include their roles (withRoles={with_roles}).
        slots:
          with_roles: query.withRoles
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a user account
      effect: write
      questions:
      - How do I add a new person as a user with a username and password?
      - What permission level can I give a brand-new user when I create them?
      instructions:
      - text: Create a new user {username} with password {password}.
        slots:
          username: requestBody.username
          password: requestBody.password
      - text: Create user {username} for {name} ({email}) with password {password} and permissions {permissions}.
        slots:
          username: requestBody.username
          name: requestBody.name
          email: requestBody.email
          password: requestBody.password
          permissions: requestBody.permissions
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user's account details
      effect: read
      questions:
      - What account details are stored for one specific user?
      - Can I look up a single user's name, email and permissions by their ID?
      instructions:
      - text: Show me the account details for user {user_id}.
        slots:
          user_id: path.user_id
      - text: Look up user {user_id} and tell me their email and permission level.
        slots:
          user_id: path.user_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a user's profile and permissions
      effect: write
      questions:
      - How do I change an existing user's display name or email address?
      - Can I change a user's permission level after the account exists?
      instructions:
      - text: Change the email of user {user_id} to {email}.
        slots:
          user_id: path.user_id
          email: requestBody.email
      - text: 'Update user {user_id}: set name to {name} and permissions to {permissions}.'
        slots:
          user_id: path.user_id
          name: requestBody.name
          permissions: requestBody.permissions
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a user account
      effect: destructive
      questions:
      - How do I permanently remove a user from the workspace?
      - When I delete a user, can their scans and objects be handed over to someone else?
      instructions:
      - text: Delete user {user_id}.
        slots:
          user_id: path.user_id
      - text: Delete user {user_id} and transfer their objects to user {successor_user_uuid}.
        slots:
          user_id: path.user_id
          successor_user_uuid: query.successor_user_uuid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/access-control/v1/users/{user_uuid}/roles'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the role assigned to a user
      effect: read
      questions:
      - Which role is currently assigned to a given user?
      - Is this user on a standard role or a custom role?
      instructions:
      - text: Tell me which role user {user_uuid} has.
        slots:
          user_uuid: path.user_uuid
      - text: Get the assigned role for user {user_uuid}.
        slots:
          user_uuid: path.user_uuid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/access-control/v1/users/{user_uuid}/roles'].put
  update:
    x-apievangelist-phrasing:
      intent: Change a user's role
      effect: write
      questions:
      - How do I move a user onto a different custom role?
      - Can I reassign someone's role using the role UUID?
      instructions:
      - text: Assign role {role_uuids} to user {user_uuid}.
        slots:
          user_uuid: path.user_uuid
          role_uuids: requestBody.role_uuids
      - text: Switch user {user_uuid} over to the roles {role_uuids}.
        slots:
          user_uuid: path.user_uuid
          role_uuids: requestBody.role_uuids
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user_uuid}/chpasswd'].put
  update:
    x-apievangelist-phrasing:
      intent: Reset a user's password
      effect: write
      questions:
      - How do I reset a locked-out user's password?
      - Can I set a temporary password that forces the user to change it at next login?
      - What are the password length and complexity rules for a reset?
      instructions:
      - text: Reset the password for user {user_uuid} to {password}.
        slots:
          user_uuid: path.user_uuid
          password: requestBody.password
      - text: Give user {user_uuid} the temporary password {password} (temporary={temporary}).
        slots:
          user_uuid: path.user_uuid
          password: requestBody.password
          temporary: requestBody.temporary
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user_id}/enabled'].put
  update:
    x-apievangelist-phrasing:
      intent: Enable or disable a user account
      effect: write
      questions:
      - How do I temporarily disable a user without deleting them?
      - Can I re-enable an account I switched off earlier?
      instructions:
      - text: Disable the account of user {user_id} (enabled={enabled}).
        slots:
          user_id: path.user_id
          enabled: requestBody.enabled
      - text: Turn user account {user_id} back on.
        slots:
          user_id: path.user_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user_id}/authorizations'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user's sign-in authorizations
      effect: read
      questions:
      - Which sign-in methods (password, SAML SSO, API keys) is a user allowed to use?
      - Is API access permitted for this particular user?
      instructions:
      - text: Show which access methods user {user_id} is authorized for.
        slots:
          user_id: path.user_id
      - text: Check whether user {user_id} can sign in with SAML or use the API.
        slots:
          user_id: path.user_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user_id}/authorizations'].put
  update:
    x-apievangelist-phrasing:
      intent: Grant or revoke a user's access methods
      effect: write
      questions:
      - How do I block a user from using the API but keep SSO login?
      - Can I require a user to enroll in multi-factor authentication?
      instructions:
      - text: For user {user_id} set API access {api_permitted}, password login {password_permitted} and SAML {saml_permitted}.
        slots:
          user_id: path.user_id
          api_permitted: requestBody.api_permitted
          password_permitted: requestBody.password_permitted
          saml_permitted: requestBody.saml_permitted
      - text: Require MFA enrollment ({mfa}) for user {user_id} with API {api_permitted}, password {password_permitted}, SAML {saml_permitted}.
        slots:
          mfa: requestBody.mfa_enrollment_required
          user_id: path.user_id
          api_permitted: requestBody.api_permitted
          password_permitted: requestBody.password_permitted
          saml_permitted: requestBody.saml_permitted
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user_id}/keys'].put
  update:
    x-apievangelist-phrasing:
      intent: Generate new API keys for a user
      effect: write
      questions:
      - How do I issue a fresh access key and secret key for a user?
      - Can an administrator generate API keys on behalf of another user?
      instructions:
      - text: Generate new API keys for user {user_id}.
        slots:
          user_id: path.user_id
      - text: Rotate the API access and secret keys of user {user_id}.
        slots:
          user_id: path.user_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user_id}/two-factor/send-verification'].post
  update:
    x-apievangelist-phrasing:
      intent: Text a two-factor verification code
      effect: write
      questions:
      - How do I start setting up SMS two-factor for a user?
      - What phone number format does the two-factor verification code need?
      instructions:
      - text: Send a two-factor verification code to {sms_phone} for user {user_id}.
        slots:
          sms_phone: requestBody.sms_phone
          user_id: path.user_id
      - text: Start 2FA setup for user {user_id} by texting a code to {sms_phone}.
        slots:
          user_id: path.user_id
          sms_phone: requestBody.sms_phone
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user_id}/two-factor/verify-code'].post
  update:
    x-apievangelist-phrasing:
      intent: Confirm a two-factor verification code
      effect: write
      questions:
      - How do I confirm the SMS code a user received so their two-factor is switched on?
      - What happens after the verification code is validated successfully?
      instructions:
      - text: Verify code {verification_code} for user {user_id} to finish enabling 2FA.
        slots:
          verification_code: requestBody.verification_code
          user_id: path.user_id
      - text: Validate the 2FA code {verification_code} that user {user_id} received by text.
        slots:
          verification_code: requestBody.verification_code
          user_id: path.user_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user_id}/two-factor'].put
  update:
    x-apievangelist-phrasing:
      intent: Configure a user's two-factor settings
      effect: write
      questions:
      - Can I turn off SMS two-factor for a user or enable backup email codes?
      - Which phone number is used once two-factor settings are saved?
      instructions:
      - text: 'Set 2FA for user {user_id}: SMS {sms_enabled} to {sms_phone}, backup email {email_enabled}.'
        slots:
          user_id: path.user_id
          sms_enabled: requestBody.sms_enabled
          sms_phone: requestBody.sms_phone
          email_enabled: requestBody.email_enabled
      - text: Disable SMS two-factor ({sms_enabled}) and email backup ({email_enabled}) for user {user_id}, phone {sms_phone}.
        slots:
          sms_enabled: requestBody.sms_enabled
          email_enabled: requestBody.email_enabled
          user_id: path.user_id
          sms_phone: requestBody.sms_phone
      method: generated
      generated: '2026-10-01'