# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Identity Platform Authz Groups Service API
  version: 1.0.0
extends: openapi/canonical-authzgroupsservice-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: 10
- target: $.paths['/api/v0/authz/groups'].get
  update:
    x-apievangelist-phrasing:
      intent: List authorization groups
      effect: read
      questions:
      - Which authorization groups are defined in the identity platform admin?
      - Can I page through groups a few at a time?
      instructions:
      - text: List all authorization groups.
      - text: List authorization groups, {size} per page, from page token {pageToken}.
        slots:
          size: query.pagination.size
          pageToken: query.pagination.pageToken
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v0/authz/groups'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an authorization group
      effect: write
      questions:
      - How do I create a new group for granting permissions?
      - Can I give a new authorization group a type and description?
      instructions:
      - text: Create authorization group {name}.
        slots:
          name: requestBody.name
      - text: Create group {name} of type {type} described as {description}.
        slots:
          name: requestBody.name
          type: requestBody.type
          description: requestBody.description
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v0/authz/groups/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an authorization group
      effect: read
      questions:
      - What are the name and type of a specific authorization group?
      - Can I look up one group by its id?
      instructions:
      - text: Show authorization group {id}.
        slots:
          id: path.id
      - text: Get the details of group {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v0/authz/groups/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an authorization group
      effect: write
      questions:
      - How do I rename an authorization group or change its description?
      - Can I change a group's type after creating it?
      instructions:
      - text: Rename authorization group {id} to {name}.
        slots:
          id: path.id
          name: requestBody.name
      - text: Set the description of group {id} to {description}.
        slots:
          id: path.id
          description: requestBody.description
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v0/authz/groups/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an authorization group
      effect: destructive
      questions:
      - How do I delete an authorization group entirely?
      - What happens to members when I remove a group?
      instructions:
      - text: Delete authorization group {id}.
        slots:
          id: path.id
      - text: Remove group {id} from the identity platform.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v0/authz/groups/{id}/users'].get
  update:
    x-apievangelist-phrasing:
      intent: List the users in an authorization group
      effect: read
      questions:
      - Who are the members of a given authorization group?
      - Can I page through a large group's user list?
      instructions:
      - text: List the users in group {id}.
        slots:
          id: path.id
      - text: Show members of group {id}, {size} at a time.
        slots:
          id: path.id
          size: query.pagination.size
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v0/authz/groups/{id}/users'].post
  update:
    x-apievangelist-phrasing:
      intent: Add users to an authorization group
      effect: write
      questions:
      - How do I add several people to one authorization group at once?
      - Can I bulk-assign users to a group?
      instructions:
      - text: Add these users to authorization group {id}.
        slots:
          id: path.id
      - text: Put the listed user accounts into group {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v0/authz/groups/{id}/users/{user_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a user from an authorization group
      effect: destructive
      questions:
      - How do I take one person out of an authorization group?
      - Does removing a user from a group revoke the permissions it granted?
      instructions:
      - text: Remove user {user_id} from group {id}.
        slots:
          user_id: path.user_id
          id: path.id
      - text: Take {user_id} out of authorization group {id}.
        slots:
          user_id: path.user_id
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v0/authz/users/{id}/groups'].get
  update:
    x-apievangelist-phrasing:
      intent: List the groups a user belongs to
      effect: read
      questions:
      - Which authorization groups is a particular user a member of?
      - Can I check a user's group memberships page by page?
      instructions:
      - text: List the groups user {id} belongs to.
        slots:
          id: path.id
      - text: Show group memberships of user {id}, {size} per page.
        slots:
          id: path.id
          size: query.pagination.size
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v0/authz/users/{id}/groups'].put
  update:
    x-apievangelist-phrasing:
      intent: Add a user to several groups
      effect: write
      questions:
      - How do I put one user into multiple authorization groups at once?
      - Can I assign a user's group memberships in a single call?
      instructions:
      - text: Add user {id} to these groups.
        slots:
          id: path.id
      - text: Assign user {id} to the listed authorization groups.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'