# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Authorization API v1.1 Roles API
  version: 1.0.0
extends: openapi/here-roles-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['/roles'].get
  update:
    x-apievangelist-phrasing:
      intent: List roles in the realm
      effect: read
      questions:
      - What roles exist in my HERE platform realm?
      - Can I find roles by name or by the resource they apply to?
      instructions:
      - text: List all roles in my realm.
      - text: Find roles named {roleName} for resource {resource}.
        slots:
          roleName: query.roleName
          resource: query.resource
      method: generated
      generated: '2026-09-26'
- target: $.paths['/roles/me'].get
  update:
    x-apievangelist-phrasing:
      intent: List the roles assigned to me
      effect: read
      questions:
      - Which roles have been assigned to my own user or app?
      - How can I check what roles the calling identity holds?
      instructions:
      - text: List the roles assigned to me.
      - text: Show up to {count} of my own roles.
        slots:
          count: query.count
      method: generated
      generated: '2026-09-26'
- target: $.paths['/roles/{role}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a role by its HRN
      effect: read
      questions:
      - How do I look up the details of a single role from its HRN?
      - What resource is a particular role attached to?
      instructions:
      - text: Get role {role}.
        slots:
          role: path.role
      - text: Show the details of the role with HRN {role}.
        slots:
          role: path.role
      method: generated
      generated: '2026-09-26'
- target: $.paths['/roles/{role}/permissions'].get
  update:
    x-apievangelist-phrasing:
      intent: List the permissions granted by a role
      effect: read
      questions:
      - What permissions does a role grant?
      - Can I see all unscoped permissions attached to a role?
      instructions:
      - text: List the permissions of role {role}.
        slots:
          role: path.role
      - text: Show what actions role {role} is allowed to perform.
        slots:
          role: path.role
      method: generated
      generated: '2026-09-26'
- target: $.paths['/roles/{role}/permissions/{permission}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one permission of a role
      effect: read
      questions:
      - How do I check a single permission on a role?
      - Does a role include a specific permission ID?
      instructions:
      - text: Get permission {permission} on role {role}.
        slots:
          permission: path.permission
          role: path.role
      - text: Check whether role {role} carries permission {permission}.
        slots:
          role: path.role
          permission: path.permission
      method: generated
      generated: '2026-09-26'
- target: $.paths['/roles/{role}/filter'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the access filter attached to a role
      effect: read
      questions:
      - Is there an access filter attached to this role?
      - Which access filter restricts the data a role can see?
      instructions:
      - text: Get the access filter attached to role {role}.
        slots:
          role: path.role
      - text: Show whether role {role} has an access filter.
        slots:
          role: path.role
      method: generated
      generated: '2026-09-26'
- target: $.paths['/roles/{role}/entities'].get
  update:
    x-apievangelist-phrasing:
      intent: List users and apps assigned a role
      effect: read
      questions:
      - Who has been assigned a given role?
      - Which users and apps hold a particular role?
      instructions:
      - text: List the entities assigned role {role}.
        slots:
          role: path.role
      - text: Show everyone who holds role {role}.
        slots:
          role: path.role
      method: generated
      generated: '2026-09-26'
- target: $.paths['/roles/{role}/entities/{entity}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check whether an entity holds a role
      effect: read
      questions:
      - How do I confirm a specific user or app has been assigned a role?
      - Does a given entity have a particular role?
      instructions:
      - text: Get entity {entity} in role {role}.
        slots:
          entity: path.entity
          role: path.role
      - text: Check if {entity} has been assigned role {role}.
        slots:
          entity: path.entity
          role: path.role
      method: generated
      generated: '2026-09-26'
- target: $.paths['/roles/{role}/entities/{entity}'].post
  update:
    x-apievangelist-phrasing:
      intent: Assign a role to a user or app
      effect: write
      questions:
      - How do I grant a role to a user or app?
      - Does an entity need to be a group member before it can get a group's role?
      instructions:
      - text: Assign role {role} to {entity}.
        slots:
          role: path.role
          entity: path.entity
      - text: Give entity {entity} the role {role}.
        slots:
          entity: path.entity
          role: path.role
      method: generated
      generated: '2026-09-26'
- target: $.paths['/roles/{role}/entities/{entity}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Revoke a role from a user or app
      effect: destructive
      questions:
      - How do I revoke a role from a user or app?
      - Can I take away one role from an entity without affecting its other roles?
      instructions:
      - text: Revoke role {role} from {entity}.
        slots:
          role: path.role
          entity: path.entity
      - text: Remove entity {entity} from role {role}.
        slots:
          entity: path.entity
          role: path.role
      method: generated
      generated: '2026-09-26'