# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Authentication API v1.1 API Key Management API
  version: 1.0.0
extends: openapi/here-api-key-management-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: 7
- target: $.paths['/apps/{app}/apiKeys'].get
  update:
    x-apievangelist-phrasing:
      intent: List an app's API keys
      effect: read
      questions:
      - Which API keys have been generated for my HERE app?
      - Can I page through all the keys on one application?
      instructions:
      - text: List the API keys for app {app}.
        slots:
          app: path.app
      - text: Show every API key generated for application {app}.
        slots:
          app: path.app
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apps/{app}/apiKeys'].post
  update:
    x-apievangelist-phrasing:
      intent: Generate a new API key for an app
      effect: write
      questions:
      - How do I create an API key to authenticate my app?
      - Can a new API key be set to expire automatically?
      - Which field in the response holds the actual key value?
      instructions:
      - text: Generate an API key named {name} for app {app}.
        slots:
          name: requestBody.name
          app: path.app
      - text: Create API key {name} on app {app} that expires at {expiresAt}.
        slots:
          name: requestBody.name
          app: path.app
          expiresAt: requestBody.expiresAt
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apps/{app}/apiKeys/{apiKey}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one API key of an app
      effect: read
      questions:
      - What are the details of a specific API key on my app?
      - Is a given API key still enabled and when does it expire?
      instructions:
      - text: Get API key {apiKey} for app {app}.
        slots:
          apiKey: path.apiKey
          app: path.app
      - text: Show the status and expiry of key {apiKey} on app {app}.
        slots:
          apiKey: path.apiKey
          app: path.app
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apps/{app}/apiKeys/{apiKey}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an app's API key permanently
      effect: destructive
      questions:
      - How do I permanently delete a leaked API key?
      - Can a deleted API key ever be recovered?
      instructions:
      - text: Delete API key {apiKey} from app {app}.
        slots:
          apiKey: path.apiKey
          app: path.app
      - text: Permanently remove key {apiKey} on application {app}.
        slots:
          apiKey: path.apiKey
          app: path.app
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apps/{app}/apiKeys/{apiKey}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Rename an API key or change its expiry
      effect: write
      questions:
      - Can I rename an existing API key?
      - How do I extend the expiration date of an API key?
      instructions:
      - text: Rename API key {apiKey} on app {app} to {name}.
        slots:
          apiKey: path.apiKey
          app: path.app
          name: requestBody.name
      - text: Change the expiry of key {apiKey} on app {app} to {expiresAt}.
        slots:
          apiKey: path.apiKey
          app: path.app
          expiresAt: requestBody.expiresAt
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apps/{app}/apiKeys/{apiKey}/enable'].post
  update:
    x-apievangelist-phrasing:
      intent: Enable a disabled API key
      effect: write
      questions:
      - How do I turn a disabled API key back on?
      - Can I reactivate a key instead of generating a new one?
      instructions:
      - text: Enable API key {apiKey} on app {app}.
        slots:
          apiKey: path.apiKey
          app: path.app
      - text: Reactivate key {apiKey} for application {app}.
        slots:
          apiKey: path.apiKey
          app: path.app
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apps/{app}/apiKeys/{apiKey}/disable'].post
  update:
    x-apievangelist-phrasing:
      intent: Disable an API key without deleting it
      effect: write
      questions:
      - Can I temporarily block an API key without deleting it?
      - What is the reversible way to stop a key from authenticating?
      instructions:
      - text: Disable API key {apiKey} on app {app}.
        slots:
          apiKey: path.apiKey
          app: path.app
      - text: Suspend key {apiKey} for application {app} so it stops working for now.
        slots:
          apiKey: path.apiKey
          app: path.app
      method: generated
      generated: '2026-09-26'