# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Cohesity REST Principals API
  version: 1.0.0
extends: openapi/cohesity-principals-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: 17
- target: $.paths['/public/principals/protectionSources'].get
  update:
    x-apievangelist-phrasing:
      intent: See which sources and views principals can access
      effect: read
      questions:
      - Which protection sources and views can a given user or group access?
      - Can I check access for several SIDs in one request?
      instructions:
      - text: List the protection sources and views that principal {sids} can access.
        slots:
          sids: query.sids
      - text: Show what objects and views SIDs {sids} have permission to see.
        slots:
          sids: query.sids
      method: generated
      generated: '2026-10-01'
- target: $.paths['/public/principals/protectionSources'].put
  update:
    x-apievangelist-phrasing:
      intent: Grant principals access to sources and views
      effect: write
      questions:
      - How do I give an Active Directory group access to specific VMs and views?
      - Can I restrict a user to only certain protection sources?
      instructions:
      - text: Set source and view access for principals as {sourcesForPrincipals}.
        slots:
          sourcesForPrincipals: requestBody.sourcesForPrincipals
      - text: 'Grant these principals access to the listed protection sources and views: {sourcesForPrincipals}.'
        slots:
          sourcesForPrincipals: requestBody.sourcesForPrincipals
      method: generated
      generated: '2026-10-01'
- target: $.paths['/public/principals/searchPrincipals'].get
  update:
    x-apievangelist-phrasing:
      intent: Search users and groups in a domain
      effect: read
      questions:
      - Can I find Active Directory users or groups whose names contain a substring?
      - Is it possible to include computer or GMSA accounts in a principal search?
      - Which principals in a domain are groups rather than users?
      instructions:
      - text: Search domain {domain} for principals matching {search}.
        slots:
          domain: query.domain
          search: query.search
      - text: Find groups in {domain} whose name contains {search}.
        slots:
          domain: query.domain
          search: query.search
      method: generated
      generated: '2026-10-01'
- target: $.paths['/public/sessionUser'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the logged-in user
      effect: read
      questions:
      - Who am I logged in as on the Cohesity cluster?
      - What roles and domain does my current session user have?
      instructions:
      - text: Show the user I'm currently logged in as.
      - text: Get my session user's details.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/public/users'].get
  update:
    x-apievangelist-phrasing:
      intent: List cluster users
      effect: read
      questions:
      - Which users have accounts on my cluster?
      - Can I find a user by email address or a partial username?
      instructions:
      - text: List users whose username contains {usernames}.
        slots:
          usernames: query.usernames
      - text: Find the cluster user with email {emailAddresses}.
        slots:
          emailAddresses: query.emailAddresses
      - text: List all users in domain {domain}.
        slots:
          domain: query.domain
      method: generated
      generated: '2026-10-01'
- target: $.paths['/public/users'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a cluster user's settings
      effect: write
      questions:
      - How do I change a user's roles on the cluster without touching Active Directory?
      - Can I force a local user to change their password at next login?
      instructions:
      - text: Update user {username} in {domain} to have roles {roles}.
        slots:
          username: requestBody.username
          domain: requestBody.domain
          roles: requestBody.roles
      - text: Force user {username} to change their password.
        slots:
          username: requestBody.username
      method: generated
      generated: '2026-10-01'
- target: $.paths['/public/users'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a user to the cluster
      effect: write
      questions:
      - How do I add an Active Directory user to my Cohesity cluster?
      - Can I create a local user with an expiry date?
      instructions:
      - text: Create local user {username} with email {emailAddress} and roles {roles}.
        slots:
          username: requestBody.username
          emailAddress: requestBody.emailAddress
          roles: requestBody.roles
      - text: Add AD user {username} from domain {domain} to the cluster.
        slots:
          username: requestBody.username
          domain: requestBody.domain
      method: generated
      generated: '2026-10-01'
- target: $.paths['/public/users'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete users from the cluster
      effect: destructive
      questions:
      - Does removing a user from the cluster also delete them in Active Directory?
      - Can I delete several users from the same domain in one go?
      instructions:
      - text: Delete users {users} from domain {domain}.
        slots:
          users: requestBody.users
          domain: requestBody.domain
      - text: Remove cluster user accounts {users}.
        slots:
          users: requestBody.users
      method: generated
      generated: '2026-10-01'
- target: $.paths['/public/users/privileges'].get
  update:
    x-apievangelist-phrasing:
      intent: List my session user's privileges
      effect: read
      questions:
      - What privileges does my current login actually have?
      - Am I allowed to manage protection jobs with my account's privileges?
      instructions:
      - text: List the privileges of my session user.
      - text: Show what I'm allowed to do on this cluster.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/public/users/s3SecretKey'].post
  update:
    x-apievangelist-phrasing:
      intent: Reset a user's S3 secret key
      effect: destructive
      questions:
      - How do I rotate the S3 secret access key for a cluster user?
      - Will resetting the S3 secret key break apps using the old one?
      instructions:
      - text: Reset the S3 secret key for user {username}.
        slots:
          username: requestBody.username
      - text: Generate a new S3 secret key for {username} in {domain}.
        slots:
          username: requestBody.username
          domain: requestBody.domain
      method: generated
      generated: '2026-10-01'
- target: $.paths['/public/users/{sid}/apiKeys'].get
  update:
    x-apievangelist-phrasing:
      intent: List a user's API keys
      effect: read
      questions:
      - Which API keys does a particular user have?
      - Can I filter a user's API keys by key id?
      instructions:
      - text: List the API keys for user {sid}.
        slots:
          sid: path.sid
      - text: Show API keys {ids} belonging to user {sid}.
        slots:
          ids: query.ids
          sid: path.sid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/public/users/{sid}/apiKeys'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an API key for a user
      effect: write
      questions:
      - How do I generate an API key for a service account user?
      - Can I give a new API key an expiration time?
      instructions:
      - text: Create API key {name} for user {sid}.
        slots:
          name: requestBody.name
          sid: path.sid
      - text: Create API key {name} for user {sid} that expires at {expiringTimeMsecs}.
        slots:
          name: requestBody.name
          sid: path.sid
          expiringTimeMsecs: requestBody.expiringTimeMsecs
      method: generated
      generated: '2026-10-01'
- target: $.paths['/public/users/{sid}/apiKeys/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one of a user's API keys
      effect: read
      questions:
      - Is a specific API key of a user still active and when does it expire?
      - Can I look up a single user API key by its id?
      instructions:
      - text: Get API key {id} for user {sid}.
        slots:
          id: path.id
          sid: path.sid
      - text: Show the details of user {sid}'s key {id}.
        slots:
          sid: path.sid
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/public/users/{sid}/apiKeys/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a user's API key
      effect: write
      questions:
      - Can I deactivate an API key without deleting it?
      - How do I extend an API key's expiration?
      instructions:
      - text: Deactivate API key {id} for user {sid}.
        slots:
          id: path.id
          sid: path.sid
      - text: Rename user {sid}'s API key {id} to {name}.
        slots:
          sid: path.sid
          id: path.id
          name: requestBody.name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/public/users/{sid}/apiKeys/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a user's API key
      effect: destructive
      questions:
      - How do I permanently remove an API key a user no longer needs?
      - What happens to clients still using an API key after it is deleted?
      instructions:
      - text: Delete API key {id} of user {sid}.
        slots:
          id: path.id
          sid: path.sid
      - text: Remove user {sid}'s key {id} for good.
        slots:
          sid: path.sid
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/public/users/{sid}/apiKeys/{id}/rotate'].post
  update:
    x-apievangelist-phrasing:
      intent: Rotate a user's API key
      effect: write
      questions:
      - Can I rotate an API key to get a fresh secret while keeping the same key entry?
      - What does rotating a user API key return?
      instructions:
      - text: Rotate API key {id} for user {sid}.
        slots:
          id: path.id
          sid: path.sid
      - text: Rotate the secret of user {sid}'s key {id}.
        slots:
          sid: path.sid
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/public/usersApiKeys'].get
  update:
    x-apievangelist-phrasing:
      intent: List API keys across all users
      effect: read
      questions:
      - Which API keys exist across every user on the cluster?
      - Can I audit API keys for a handful of users at once?
      instructions:
      - text: List API keys across all users.
      - text: Show the API keys owned by users {userSids}.
        slots:
          userSids: query.userSids
      method: generated
      generated: '2026-10-01'