# 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 Realms API
  version: 1.0.0
extends: openapi/here-realms-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: 37
- target: $.paths['/realms/{realm}/invites/{invite}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update and resend a pending realm invitation
      effect: write
      questions:
      - Can I fix the email address on an invitation I already sent to my HERE organization and send it again?
      - How do I change the roles or groups on a pending realm invite before the person accepts?
      instructions:
      - text: Update invite {invite} in realm {realm} to go to {emailAddress} and resend it.
        slots:
          invite: path.invite
          realm: path.realm
          emailAddress: requestBody.emailAddress
      - text: Change the groups on pending invite {invite} in realm {realm} to {groupHrns} and send the updated invitation to {emailAddress}.
        slots:
          invite: path.invite
          realm: path.realm
          groupHrns: requestBody.groupHrns
          emailAddress: requestBody.emailAddress
      method: generated
      generated: '2026-09-26'
- target: $.paths['/realms/{realm}/invites/{invite}'].post
  update:
    x-apievangelist-phrasing:
      intent: Resend an existing realm invitation unchanged
      effect: write
      questions:
      - Someone lost their invitation email to our realm, can it be sent again as-is?
      - Is there a way to nudge an invitee by resending the same realm invite without editing it?
      instructions:
      - text: Resend invitation {invite} for realm {realm} without changing it.
        slots:
          invite: path.invite
          realm: path.realm
      - text: Send the realm {realm} invite {invite} email again.
        slots:
          realm: path.realm
          invite: path.invite
      method: generated
      generated: '2026-09-26'
- target: $.paths['/realms/{realm}/invites/{invite}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Cancel a pending realm invitation
      effect: destructive
      questions:
      - How do I revoke an invitation I sent to the wrong person for my realm?
      - Can an outstanding realm invite be withdrawn before it is accepted?
      instructions:
      - text: Cancel invitation {invite} in realm {realm}.
        slots:
          invite: path.invite
          realm: path.realm
      - text: Withdraw the pending realm {realm} invite {invite} so it can no longer be accepted.
        slots:
          realm: path.realm
          invite: path.invite
      method: generated
      generated: '2026-09-26'
- target: $.paths['/realms/{realm}/invites'].get
  update:
    x-apievangelist-phrasing:
      intent: Search invitations in a realm
      effect: read
      questions:
      - Which invitations to my HERE realm are still outstanding?
      - Can I filter realm invitations to only those tied to a particular group?
      instructions:
      - text: Search invitations in realm {realm} matching {q}.
        slots:
          realm: path.realm
          q: query.q
      - text: List the invitations in realm {realm} that add people to group {group}.
        slots:
          realm: path.realm
          group: query.group
      method: generated
      generated: '2026-09-26'
- target: $.paths['/realms/{realm}/invites'].post
  update:
    x-apievangelist-phrasing:
      intent: Invite a new user to a realm
      effect: write
      questions:
      - How do I invite a colleague to join my HERE platform organization?
      - Can I put a new user straight into groups when I first invite them to the realm?
      - Is it possible to let an invited user sign in with a password rather than only SSO?
      instructions:
      - text: Invite {emailAddress} to realm {realm}.
        slots:
          emailAddress: requestBody.emailAddress
          realm: path.realm
      - text: Send a new realm {realm} invitation to {firstName} {lastName} at {emailAddress} and add them to groups {groupHrns}.
        slots:
          realm: path.realm
          firstName: requestBody.firstName
          lastName: requestBody.lastName
          emailAddress: requestBody.emailAddress
          groupHrns: requestBody.groupHrns
      method: generated
      generated: '2026-09-26'
- target: $.paths['/realms/{realm}/invites/targets'].get
  update:
    x-apievangelist-phrasing:
      intent: List invite targets available for a realm
      effect: read
      questions:
      - Which applications can an invitation email send new members to in my realm?
      - What invite targets besides the default platform one does my realm support?
      instructions:
      - text: Show the supported invite targets for realm {realm}.
        slots:
          realm: path.realm
      - text: List where invitation emails for realm {realm} can direct new users.
        slots:
          realm: path.realm
      method: generated
      generated: '2026-09-26'
- target: $.paths['/realms/{realm}/limits'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the limits configured for a realm
      effect: read
      questions:
      - What limits apply to my HERE organization's realm?
      - If the same limit type shows up twice, which value is actually enforced on my realm?
      instructions:
      - text: Show the configured limits for realm {realm}.
        slots:
          realm: path.realm
      - text: List realm {realm} limits of type {type}.
        slots:
          realm: path.realm
          type: query.type
      method: generated
      generated: '2026-09-26'
- target: $.paths['/realms/{realm}/members'].get
  update:
    x-apievangelist-phrasing:
      intent: List members of a realm
      effect: read
      questions:
      - Who are all the users and apps in my HERE realm?
      - Can I list only the car entities in the realm with a certain vehicle contract?
      - Is there a way to find realm members by name or email?
      instructions:
      - text: List all members of realm {realm}.
        slots:
          realm: path.realm
      - text: Find members of realm {realm} of type {entityType} matching {q}.
        slots:
          realm: path.realm
          entityType: query.entityType
          q: query.q
      method: generated
      generated: '2026-09-26'
- target: $.paths['/realms/{realm}/members/{member}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get details of one realm member
      effect: read
      questions:
      - How can I look up the details of a specific user or app in my realm by its HRN?
      - What does the realm know about a single member account?
      instructions:
      - text: Get the details of member {member} in realm {realm}.
        slots:
          member: path.member
          realm: path.realm
      - text: Look up realm {realm} member {member}.
        slots:
          realm: path.realm
          member: path.member
      method: generated
      generated: '2026-09-26'
- target: $.paths['/realms/{realm}/members/{member}/roles'].get
  update:
    x-apievangelist-phrasing:
      intent: List roles assigned to a realm member
      effect: read
      questions:
      - What roles has a particular user or app been given in my realm?
      - Can I check whether a member holds any admin roles?
      instructions:
      - text: List the roles assigned to member {member} in realm {realm}.
        slots:
          member: path.member
          realm: path.realm
      - text: Show which roles {member} holds in realm {realm}.
        slots:
          member: path.member
          realm: path.realm
      method: generated
      generated: '2026-09-26'
- target: $.paths['/realms/{realm}/members/{member}/groups'].get
  update:
    x-apievangelist-phrasing:
      intent: List groups a realm member belongs to
      effect: read
      questions:
      - Which groups is a given user a member of in our realm?
      - Can I see every group an app has joined?
      instructions:
      - text: List the groups member {member} belongs to in realm {realm}.
        slots:
          member: path.member
          realm: path.realm
      - text: Show group memberships for {member} in realm {realm}.
        slots:
          member: path.member
          realm: path.realm
      method: generated
      generated: '2026-09-26'
- target: $.paths['/realms/{realm}/members/{member}/managedGroups'].get
  update:
    x-apievangelist-phrasing:
      intent: List groups a member administers
      effect: read
      questions:
      - Which groups is this user a GroupAdmin for?
      - What groups can a particular member manage in the realm?
      instructions:
      - text: List the groups that member {member} is GroupAdmin of in realm {realm}.
        slots:
          member: path.member
          realm: path.realm
      - text: Show the groups {member} manages in realm {realm}.
        slots:
          member: path.member
          realm: path.realm
      method: generated
      generated: '2026-09-26'
- target: $.paths['/realms/{realm}/members/{member}/projects'].get
  update:
    x-apievangelist-phrasing:
      intent: List projects a realm member belongs to
      effect: read
      questions:
      - Which projects is a specific user or app a member of?
      - Can I audit the project access of one member in my realm?
      instructions:
      - text: List the projects member {member} belongs to in realm {realm}.
        slots:
          member: path.member
          realm: path.realm
      - text: Show project memberships for {member} in realm {realm}.
        slots:
          member: path.member
          realm: path.realm
      method: generated
      generated: '2026-09-26'
- target: $.paths['/realms/{realm}/members/{member}/plans'].get
  update:
    x-apievangelist-phrasing:
      intent: List plans attached to an app member
      effect: read
      questions:
      - Which plans are attached to one of my apps in the realm?
      - Why do I get a 404 when asking for plans on a user instead of an app?
      instructions:
      - text: List the plans attached to app member {member} in realm {realm}.
        slots:
          member: path.member
          realm: path.realm
      - text: Show plans assigned to {member} in realm {realm}.
        slots:
          member: path.member
          realm: path.realm
      method: generated
      generated: '2026-09-26'
- target: $.paths['/realms/{realm}/members/{member}/plans/{plan}/policies'].get
  update:
    x-apievangelist-phrasing:
      intent: List policies in a plan attached to a member
      effect: read
      questions:
      - What policies come with a plan that is attached to my app?
      - Can I see which policies a member gets through a specific plan?
      instructions:
      - text: List the policies in plan {plan} attached to member {member} in realm {realm}.
        slots:
          plan: path.plan
          member: path.member
          realm: path.realm
      - text: Show what policies member {member} receives via plan {plan} in realm {realm}.
        slots:
          member: path.member
          plan: path.plan
          realm: path.realm
      method: generated
      generated: '2026-09-26'
- target: $.paths['/realms/{realm}/members/{member}/plans/{plan}/policies/{policy}/permissions'].get
  update:
    x-apievangelist-phrasing:
      intent: List permissions in a member's plan policy
      effect: read
      questions:
      - Which unscoped permissions does a policy inside my app's plan actually grant?
      - Can I drill from a member's plan down to the permissions of one of its policies?
      instructions:
      - text: List permissions of policy {policy} in plan {plan} for member {member} in realm {realm}.
        slots:
          policy: path.policy
          plan: path.plan
          member: path.member
          realm: path.realm
      - text: Show what policy {policy} from member {member}'s plan {plan} grants in realm {realm}.
        slots:
          policy: path.policy
          member: path.member
          plan: path.plan
          realm: path.realm
      method: generated
      generated: '2026-09-26'
- target: $.paths['/realms/{realm}/members/{member}/policies'].get
  update:
    x-apievangelist-phrasing:
      intent: List policies attached directly to an app member
      effect: read
      questions:
      - Which policies are attached directly to my app, outside of any plan?
      - Can policies be attached to a user member or only to apps?
      instructions:
      - text: List policies attached directly to member {member} in realm {realm}.
        slots:
          member: path.member
          realm: path.realm
      - text: Show the policies on app member {member} in realm {realm}.
        slots:
          member: path.member
          realm: path.realm
      method: generated
      generated: '2026-09-26'
- target: $.paths['/realms/{realm}/members/{member}/policies/{policy}/permissions'].get
  update:
    x-apievangelist-phrasing:
      intent: List permissions in a policy attached to a member
      effect: read
      questions:
      - What unscoped permissions does a policy attached straight to my app grant?
      - Can I see the permissions inside one directly attached member policy?
      instructions:
      - text: List permissions in policy {policy} attached directly to member {member} in realm {realm}.
        slots:
          policy: path.policy
          member: path.member
          realm: path.realm
      - text: Show what member {member}'s directly attached policy {policy} allows in realm {realm}.
        slots:
          member: path.member
          policy: path.policy
          realm: path.realm
      method: generated
      generated: '2026-09-26'
- target: $.paths['/realms/{realm}/members/{member}/permissions'].get
  update:
    x-apievangelist-phrasing:
      intent: List permissions assigned to a realm member
      effect: read
      questions:
      - What unscoped permissions has a particular user been granted overall?
      - Can I narrow a member's permissions to just one service?
      instructions:
      - text: List all permissions assigned to member {member} in realm {realm}.
        slots:
          member: path.member
          realm: path.realm
      - text: Show member {member}'s permissions for service {serviceId} in realm {realm}.
        slots:
          member: path.member
          serviceId: query.serviceId
          realm: path.realm
      method: generated
      generated: '2026-09-26'
- target: $.paths['/realms/{realm}/members/{member}/filters'].get
  update:
    x-apievangelist-phrasing:
      intent: List access filters attached to a member
      effect: read
      questions:
      - Which access filters currently restrict a given user or app?
      - How many access filters are attached to one realm member?
      instructions:
      - text: List access filters attached to member {member} in realm {realm}.
        slots:
          member: path.member
          realm: path.realm
      - text: Show every access filter on {member} in realm {realm}.
        slots:
          member: path.member
          realm: path.realm
      method: generated
      generated: '2026-09-26'
- target: $.paths['/realms/{realm}/members/{member}/filters/{filterHrn}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one access filter attached to a member
      effect: read
      questions:
      - Is a specific access filter attached to this member, and when does it expire?
      - Can I inspect a single access filter on a user by its HRN?
      instructions:
      - text: Get access filter {filterHrn} attached to member {member} in realm {realm}.
        slots:
          filterHrn: path.filterHrn
          member: path.member
          realm: path.realm
      - text: Check whether filter {filterHrn} is on {member} in realm {realm}.
        slots:
          filterHrn: path.filterHrn
          member: path.member
          realm: path.realm
      method: generated
      generated: '2026-09-26'
- target: $.paths['/realms/{realm}/members/{member}/filters/{filterHrn}'].put
  update:
    x-apievangelist-phrasing:
      intent: Attach an access filter to a member
      effect: write
      questions:
      - How do I restrict a single user with an access filter that expires later?
      - What is the maximum number of access filters one member can have?
      instructions:
      - text: Attach access filter {filterHrn} to member {member} in realm {realm}.
        slots:
          filterHrn: path.filterHrn
          member: path.member
          realm: path.realm
      - text: Apply filter {filterHrn} to {member} in realm {realm} until {expiresAt}.
        slots:
          filterHrn: path.filterHrn
          member: path.member
          realm: path.realm
          expiresAt: requestBody.expiresAt
      method: generated
      generated: '2026-09-26'
- target: $.paths['/realms/{realm}/members/{member}/filters/{filterHrn}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Detach an access filter from a member
      effect: destructive
      questions:
      - How can I lift an access filter restriction from one user?
      - Can I remove a single access filter from an app member?
      instructions:
      - text: Detach access filter {filterHrn} from member {member} in realm {realm}.
        slots:
          filterHrn: path.filterHrn
          member: path.member
          realm: path.realm
      - text: Remove filter {filterHrn} from {member} in realm {realm}.
        slots:
          filterHrn: path.filterHrn
          member: path.member
          realm: path.realm
      method: generated
      generated: '2026-09-26'
- target: $.paths['/realms/{realm}/plans'].get
  update:
    x-apievangelist-phrasing:
      intent: List plans attached to a realm
      effect: read
      questions:
      - Which plans does my whole HERE organization have attached?
      - Can I list only the realm's plans for one service?
      instructions:
      - text: List the plans attached to realm {realm}.
        slots:
          realm: path.realm
      - text: Show realm {realm} plans for service {serviceId}.
        slots:
          realm: path.realm
          serviceId: query.serviceId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/realms/{realm}/plans/{plan}/policies'].get
  update:
    x-apievangelist-phrasing:
      intent: List policies in a plan attached to a realm
      effect: read
      questions:
      - What policies are bundled into one of my organization's plans?
      - Can I break a realm-level plan down into its policies?
      instructions:
      - text: List the policies in realm plan {plan} for realm {realm}.
        slots:
          plan: path.plan
          realm: path.realm
      - text: Show which policies realm {realm}'s plan {plan} includes.
        slots:
          realm: path.realm
          plan: path.plan
      method: generated
      generated: '2026-09-26'
- target: $.paths['/realms/{realm}/plans/{plan}/policies/{policy}/permissions'].get
  update:
    x-apievangelist-phrasing:
      intent: List permissions in a realm plan's policy
      effect: read
      questions:
      - Which permissions does a policy inside my organization's plan grant?
      - Can I see the unscoped permissions of one policy in a realm-attached plan?
      instructions:
      - text: Show the organization-level plan {plan} policy {policy} permissions for realm {realm}.
        slots:
          policy: path.policy
          plan: path.plan
          realm: path.realm
      - text: Show what policy {policy} in organization plan {plan} allows in realm {realm}.
        slots:
          policy: path.policy
          plan: path.plan
          realm: path.realm
      method: generated
      generated: '2026-09-26'
- target: $.paths['/realms/{realm}/policies'].get
  update:
    x-apievangelist-phrasing:
      intent: List policies attached directly to a realm
      effect: read
      questions:
      - Which policies are attached to my realm itself rather than through a plan?
      - Can I filter realm policies by service?
      instructions:
      - text: List the policies attached directly to realm {realm}.
        slots:
          realm: path.realm
      - text: Show realm {realm} policies for service {serviceId}.
        slots:
          realm: path.realm
          serviceId: query.serviceId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/realms/{realm}/policies/{policy}/permissions'].get
  update:
    x-apievangelist-phrasing:
      intent: List permissions in a realm-attached policy
      effect: read
      questions:
      - What does a policy attached directly to my realm actually permit?
      - Can I list the unscoped permissions of a realm policy outside any plan?
      instructions:
      - text: List permissions of realm policy {policy} in realm {realm}.
        slots:
          policy: path.policy
          realm: path.realm
      - text: Show what directly attached policy {policy} grants in realm {realm}.
        slots:
          policy: path.policy
          realm: path.realm
      method: generated
      generated: '2026-09-26'
- target: $.paths['/realms/{realm}/resourcePlans'].get
  update:
    x-apievangelist-phrasing:
      intent: List resource plans attached to a realm
      effect: read
      questions:
      - Which resource plans has my organization been given?
      - Are there any resource plans attached to our realm?
      instructions:
      - text: Enumerate the resource plans (not ordinary plans) on realm {realm}.
        slots:
          realm: path.realm
      - text: Show all resource plans for realm {realm}.
        slots:
          realm: path.realm
      method: generated
      generated: '2026-09-26'
- target: $.paths['/realms/{realm}/resourcePlans/{resourcePlan}/resourcePolicies'].get
  update:
    x-apievangelist-phrasing:
      intent: List resource policies in a realm resource plan
      effect: read
      questions:
      - Which resource policies are packaged inside a resource plan on my realm?
      - Can I see the resource policies a resource plan shares with my organization?
      instructions:
      - text: List resource policies in resource plan {resourcePlan} for realm {realm}.
        slots:
          resourcePlan: path.resourcePlan
          realm: path.realm
      - text: Show the resource policies that resource plan {resourcePlan} brings to realm {realm}.
        slots:
          resourcePlan: path.resourcePlan
          realm: path.realm
      method: generated
      generated: '2026-09-26'
- target: $.paths['/realms/{realm}/resourcePlans/{resourcePlan}/resourcePolicies/{resourcePolicy}/permissions'].get
  update:
    x-apievangelist-phrasing:
      intent: List linkable permissions in a resource plan's policy
      effect: read
      questions:
      - What linkable permissions does a resource policy in my resource plan offer?
      - Can I see which resources I can link to projects from a resource plan's policy?
      instructions:
      - text: List linkable permissions of resource policy {resourcePolicy} in resource plan {resourcePlan} for realm {realm}.
        slots:
          resourcePolicy: path.resourcePolicy
          resourcePlan: path.resourcePlan
          realm: path.realm
      - text: Show what resource policy {resourcePolicy} from resource plan {resourcePlan} lets realm {realm} link.
        slots:
          resourcePolicy: path.resourcePolicy
          resourcePlan: path.resourcePlan
          realm: path.realm
      method: generated
      generated: '2026-09-26'
- target: $.paths['/realms/{realm}/resourcePlans/{resourcePlan}/actionPolicies'].get
  update:
    x-apievangelist-phrasing:
      intent: List service action policies in a resource plan
      effect: read
      questions:
      - Which service action policies come with a resource plan on my realm?
      - Does a resource plan include action policies as well as resource policies?
      instructions:
      - text: List service action policies in resource plan {resourcePlan} for realm {realm}.
        slots:
          resourcePlan: path.resourcePlan
          realm: path.realm
      - text: Show the action policies bundled in resource plan {resourcePlan} on realm {realm}.
        slots:
          resourcePlan: path.resourcePlan
          realm: path.realm
      method: generated
      generated: '2026-09-26'
- target: $.paths['/realms/{realm}/resourcePlans/{resourcePlan}/actionPolicies/{actionPolicy}/permissions'].get
  update:
    x-apievangelist-phrasing:
      intent: List permissions in a resource plan's action policy
      effect: read
      questions:
      - Which permissions does one service action policy in my resource plan grant?
      - Can I drill into an action policy of a resource plan to see its permissions?
      instructions:
      - text: List permissions of action policy {actionPolicy} in resource plan {resourcePlan} for realm {realm}.
        slots:
          actionPolicy: path.actionPolicy
          resourcePlan: path.resourcePlan
          realm: path.realm
      - text: Show what service action policy {actionPolicy} in resource plan {resourcePlan} allows in realm {realm}.
        slots:
          actionPolicy: path.actionPolicy
          resourcePlan: path.resourcePlan
          realm: path.realm
      method: generated
      generated: '2026-09-26'
- target: $.paths['/realms/{realm}/linkable/permissions'].get
  update:
    x-apievangelist-phrasing:
      intent: List linkable permissions available in a realm
      effect: read
      questions:
      - Which resources in my realm have been made linkable to any project?
      - Can I list linkable permissions for just one resource type, like catalogs?
      instructions:
      - text: List linkable permissions in realm {realm} for resource type {resourceType}.
        slots:
          realm: path.realm
          resourceType: query.resourceType
      - text: Show realm {realm} linkable permissions for {resourceType} resources from service {serviceId}.
        slots:
          realm: path.realm
          resourceType: query.resourceType
          serviceId: query.serviceId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/realms/{realm}/filter'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the access filter on a realm
      effect: read
      questions:
      - Is there an access filter restricting my whole organization's realm?
      - Which access filter is currently attached at the realm level?
      instructions:
      - text: Get the access filter attached to realm {realm}.
        slots:
          realm: path.realm
      - text: Show the realm-wide access filter for {realm}.
        slots:
          realm: path.realm
      method: generated
      generated: '2026-09-26'
- target: $.paths['/realms/{realm}/filter'].post
  update:
    x-apievangelist-phrasing:
      intent: Set or replace a realm's access filter
      effect: write
      questions:
      - How do I apply an access filter to my entire realm?
      - What happens to the existing realm access filter if I attach a new one?
      instructions:
      - text: Attach access filter {hrn} to realm {realm}, replacing any existing one.
        slots:
          hrn: requestBody.hrn
          realm: path.realm
      - text: Set the realm-wide access filter for {realm} to {hrn}.
        slots:
          realm: path.realm
          hrn: requestBody.hrn
      method: generated
      generated: '2026-09-26'
- target: $.paths['/realms/{realm}/permissions'].get
  update:
    x-apievangelist-phrasing:
      intent: Get effective permissions of a realm
      effect: read
      questions:
      - What effective permissions does my organization's realm hold?
      - Can I page through every permission the realm has?
      instructions:
      - text: List the effective permissions of realm {realm}.
        slots:
          realm: path.realm
      - text: Show what realm {realm} as a whole is permitted to do.
        slots:
          realm: path.realm
      method: generated
      generated: '2026-09-26'