# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Management Accounts and users API
  version: 1.0.0
extends: openapi/talon-one-accounts-and-users-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 30
- target: $.paths['/v1/users'].get
  update:
    x-apievangelist-phrasing:
      intent: List the users in my account
      effect: read
      questions:
      - Who has a login to our Talon.One account?
      - Can I page through every user on the account sorted by a field?
      instructions:
      - text: List all users in my account.
      - text: Show the users in my account, {pageSize} per page, skipping the first {skip}.
        slots:
          pageSize: query.pageSize
          skip: query.skip
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/users/{userId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one user's details
      effect: read
      questions:
      - What details, including the invitation code, are stored for a specific account user?
      - Can a non-admin user look up anyone's profile or only their own?
      instructions:
      - text: Get the details of user {userId}.
        slots:
          userId: path.userId
      - text: Show me the invitation code for user {userId}.
        slots:
          userId: path.userId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/users/{userId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a user's name, role or admin status
      effect: write
      questions:
      - How do I make an existing account user an admin?
      - Can I change which roles a user has and their notification subscriptions?
      instructions:
      - text: Rename user {userId} to {name}.
        slots:
          userId: path.userId
          name: requestBody.name
      - text: Assign roles {roles} to user {userId}.
        slots:
          roles: requestBody.roles
          userId: path.userId
      - text: Set the state of user {userId} to {state}.
        slots:
          userId: path.userId
          state: requestBody.state
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/users/{userId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a user by ID
      effect: destructive
      questions:
      - What happens when I remove a user from the account using their user ID?
      - Is deleting an account user by ID permanent?
      instructions:
      - text: Delete user {userId} from my account.
        slots:
          userId: path.userId
      - text: Remove the account user with ID {userId}.
        slots:
          userId: path.userId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/provisioning/okta'].get
  update:
    x-apievangelist-phrasing:
      intent: Answer Okta's ownership verification challenge
      effect: read
      questions:
      - How does Okta verify it is talking to the right endpoint before provisioning users?
      - Which endpoint answers the Okta challenge-response check for user provisioning?
      instructions:
      - text: Run the Okta API ownership validation challenge.
      - text: Verify the Okta provisioning connection is reachable.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/provisioning/scim/Groups'].get
  update:
    x-apievangelist-phrasing:
      intent: List groups provisioned through SCIM
      effect: read
      questions:
      - Which role groups has our identity provider created over SCIM?
      - Can I see the members of every SCIM-provisioned group?
      instructions:
      - text: List all SCIM groups.
      - text: Show every role group provisioned by our identity provider.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/provisioning/scim/Groups'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a role group over SCIM
      effect: write
      questions:
      - How do I create a role from Entra ID using SCIM group provisioning?
      - Can I add members at the same time I create a SCIM group?
      instructions:
      - text: Create a SCIM group named {displayName}.
        slots:
          displayName: requestBody.displayName
      - text: Create a SCIM group {displayName} with members {members}.
        slots:
          displayName: requestBody.displayName
          members: requestBody.members
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/provisioning/scim/Groups/{groupId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one SCIM group
      effect: read
      questions:
      - Who are the members of a particular SCIM-provisioned group?
      - What does one SCIM group look like in Talon.One?
      instructions:
      - text: Get SCIM group {groupId}.
        slots:
          groupId: path.groupId
      - text: Show the members of SCIM group {groupId}.
        slots:
          groupId: path.groupId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/provisioning/scim/Groups/{groupId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace all attributes of a SCIM group
      effect: write
      questions:
      - Can I overwrite a SCIM group's name and full member list in one request?
      - What happens to attributes I leave out when I replace a SCIM group?
      instructions:
      - text: Replace SCIM group {groupId} with name {displayName} and members {members}.
        slots:
          groupId: path.groupId
          displayName: requestBody.displayName
          members: requestBody.members
      - text: Fully overwrite the attributes of SCIM group {groupId}.
        slots:
          groupId: path.groupId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/provisioning/scim/Groups/{groupId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a SCIM group
      effect: destructive
      questions:
      - How do I remove a role group that was provisioned over SCIM?
      - Does deleting a SCIM group remove the role it corresponds to?
      instructions:
      - text: Delete SCIM group {groupId}.
        slots:
          groupId: path.groupId
      - text: Deprovision the SCIM group {groupId}.
        slots:
          groupId: path.groupId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/provisioning/scim/Groups/{groupId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Add, remove or replace specific SCIM group attributes
      effect: write
      questions:
      - Can I add one member to a SCIM group without resending the whole group?
      - Which patch operations can I apply selectively to a SCIM group?
      instructions:
      - text: Apply patch operations {Operations} to SCIM group {groupId}.
        slots:
          Operations: requestBody.Operations
          groupId: path.groupId
      - text: Patch SCIM group {groupId} to add a single member, leaving other attributes unchanged.
        slots:
          groupId: path.groupId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/provisioning/scim/Users'].get
  update:
    x-apievangelist-phrasing:
      intent: List users provisioned through SCIM
      effect: read
      questions:
      - Which users were provisioned by our identity provider via SCIM?
      - Can I get a paginated list of SCIM users?
      instructions:
      - text: List all SCIM-provisioned users.
      - text: Show the users our identity provider created over SCIM.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/provisioning/scim/Users'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a user over SCIM
      effect: write
      questions:
      - How do I provision a new user from Entra ID with SCIM?
      - Can I create a SCIM user as inactive?
      instructions:
      - text: Create SCIM user {userName} with display name {displayName}.
        slots:
          userName: requestBody.userName
          displayName: requestBody.displayName
      - text: Provision SCIM user {userName} with active set to {active}.
        slots:
          userName: requestBody.userName
          active: requestBody.active
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/provisioning/scim/Users/{userId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one SCIM-provisioned user
      effect: read
      questions:
      - What data does Talon.One hold for a user created through SCIM?
      - Is a particular SCIM user still active?
      instructions:
      - text: Get SCIM user {userId}.
        slots:
          userId: path.userId
      - text: Show the SCIM record for user {userId}.
        slots:
          userId: path.userId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/provisioning/scim/Users/{userId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace all attributes of a SCIM user
      effect: write
      questions:
      - Can I overwrite every attribute of a SCIM user in a single request?
      - What happens to fields I omit when replacing a SCIM user?
      instructions:
      - text: Replace SCIM user {userId} with user name {userName} and display name {displayName}.
        slots:
          userId: path.userId
          userName: requestBody.userName
          displayName: requestBody.displayName
      - text: Fully overwrite SCIM user {userId}, setting active to {active}.
        slots:
          userId: path.userId
          active: requestBody.active
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/provisioning/scim/Users/{userId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a SCIM-provisioned user
      effect: destructive
      questions:
      - How do I deprovision a user our identity provider created over SCIM?
      - Does removing a SCIM user delete their Talon.One login?
      instructions:
      - text: Delete SCIM user {userId}.
        slots:
          userId: path.userId
      - text: Deprovision SCIM user {userId}.
        slots:
          userId: path.userId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/provisioning/scim/Users/{userId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update specific attributes of a SCIM user
      effect: write
      questions:
      - Can I deactivate a SCIM user by patching just the active attribute?
      - Which SCIM user attributes can I add, remove or replace selectively?
      instructions:
      - text: Apply patch operations {Operations} to SCIM user {userId}.
        slots:
          Operations: requestBody.Operations
          userId: path.userId
      - text: Patch only the display name of SCIM user {userId}, leaving other attributes unchanged.
        slots:
          userId: path.userId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/provisioning/scim/ResourceTypes'].get
  update:
    x-apievangelist-phrasing:
      intent: List supported SCIM resource types
      effect: read
      questions:
      - Which SCIM resource types can be managed, such as users and groups?
      - What resource types does the SCIM API expose?
      instructions:
      - text: List the SCIM resource types supported.
      - text: Show which resource types the SCIM API can manage.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/provisioning/scim/ServiceProviderConfig'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the SCIM service provider configuration
      effect: read
      questions:
      - Which SCIM features and operation settings are supported?
      - Does the SCIM service support patch operations according to its configuration?
      instructions:
      - text: Get the SCIM service provider configuration.
      - text: Show the capabilities the SCIM service provider advertises.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/provisioning/scim/Schemas'].get
  update:
    x-apievangelist-phrasing:
      intent: List supported SCIM schemas
      effect: read
      questions:
      - What attributes do the SCIM user and group schemas define?
      - Which SCIM schemas are supported for provisioning?
      instructions:
      - text: List the supported SCIM schemas.
      - text: Show the structure of the SCIM schemas used for provisioning.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/users/delete'].post
  update:
    x-apievangelist-phrasing:
      intent: Delete a user by email address
      effect: destructive
      questions:
      - Can I delete an account user when I only know their email?
      - What is the way to remove a teammate's user account by email address?
      instructions:
      - text: Delete the user with email {email}.
        slots:
          email: requestBody.email
      - text: Remove the account user whose email address is {email}.
        slots:
          email: requestBody.email
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/users/activate'].post
  update:
    x-apievangelist-phrasing:
      intent: Re-enable a disabled user by email
      effect: write
      questions:
      - How do I re-enable a user I previously disabled?
      - Can I reactivate a disabled account user using their email?
      instructions:
      - text: Enable the disabled user with email {email}.
        slots:
          email: requestBody.email
      - text: Reactivate the user {email}.
        slots:
          email: requestBody.email
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/users/deactivate'].post
  update:
    x-apievangelist-phrasing:
      intent: Disable a user by email
      effect: write
      questions:
      - Can I block a user's access without deleting them?
      - What is the way to disable a user account by email address?
      instructions:
      - text: Disable the user with email {email}.
        slots:
          email: requestBody.email
      - text: Suspend access for user {email} without deleting them.
        slots:
          email: requestBody.email
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/users/invite'].post
  update:
    x-apievangelist-phrasing:
      intent: Invite a user from an external identity provider
      effect: write
      questions:
      - How do I invite someone from our identity provider into Talon.One?
      - Can I put an externally invited user into user groups on invite?
      instructions:
      - text: Invite {email} from our identity provider.
        slots:
          email: requestBody.email
      - text: Send an identity provider invitation to {email} named {name} in groups {userGroups}.
        slots:
          email: requestBody.email
          name: requestBody.name
          userGroups: requestBody.userGroups
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/invites'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new user and send them an invitation
      effect: write
      questions:
      - How long is a new user's invitation token valid?
      - Can I set roles or admin rights when inviting a new user to the account?
      instructions:
      - text: Invite {email} as a new user of my account.
        slots:
          email: requestBody.email
      - text: Create user {name} with email {email} and roles {roles}, and send the invite.
        slots:
          name: requestBody.name
          email: requestBody.email
          roles: requestBody.roles
      - text: Invite {email} as an admin with isAdmin {isAdmin}.
        slots:
          email: requestBody.email
          isAdmin: requestBody.isAdmin
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/invite_emails'].post
  update:
    x-apievangelist-phrasing:
      intent: Resend an invitation email
      effect: write
      questions:
      - A user's invitation expired, can I send it again?
      - What do I need to resend an invite to an existing user?
      instructions:
      - text: Resend the invitation email to {email} with token {token}.
        slots:
          email: requestBody.email
          token: requestBody.token
      - text: Send the invite to {email} again using invitation token {token}.
        slots:
          email: requestBody.email
          token: requestBody.token
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/password_recovery_emails'].post
  update:
    x-apievangelist-phrasing:
      intent: Send a password recovery email
      effect: write
      questions:
      - I forgot my password, how can I get a reset link?
      - How long does a password recovery link stay valid?
      instructions:
      - text: Send a password reset email to {email}.
        slots:
          email: requestBody.email
      - text: Email a password recovery link to {email}.
        slots:
          email: requestBody.email
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/reset_password'].post
  update:
    x-apievangelist-phrasing:
      intent: Set a new password with a reset token
      effect: write
      questions:
      - How do I use a password reset token to set a new password?
      - Can a password reset token be used more than once?
      instructions:
      - text: Reset my password to {password} using reset token {resetToken}.
        slots:
          password: requestBody.password
          resetToken: requestBody.resetToken
      - text: Consume reset token {resetToken} and set the new password {password}.
        slots:
          resetToken: requestBody.resetToken
          password: requestBody.password
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/accounts/{accountId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get my company's account details
      effect: read
      questions:
      - What details are stored for our company's Talon.One account?
      - Where can I look up our account's configuration by account ID?
      instructions:
      - text: Get the details of account {accountId}.
        slots:
          accountId: path.accountId
      - text: Show my company account {accountId}.
        slots:
          accountId: path.accountId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/accounts/{accountId}/analytics'].get
  update:
    x-apievangelist-phrasing:
      intent: Get account-level analytics
      effect: read
      questions:
      - What analytics does Talon.One report for our whole account?
      - Where can I pull account-wide analytics by account ID?
      instructions:
      - text: Get the analytics for account {accountId}.
        slots:
          accountId: path.accountId
      - text: Show account-level analytics for {accountId}.
        slots:
          accountId: path.accountId
      method: generated
      generated: '2026-09-26'