# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Clerk Com API Keys API
  version: 1.0.0
extends: openapi/clerk-com-api-keys-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: 8
- target: $.paths['/api_keys'].get
  update:
    x-apievangelist-phrasing:
      intent: List API keys for a subject
      effect: read
      questions:
      - Which API keys have been issued to a given user or organization?
      - Can I include revoked or expired keys when listing API keys?
      instructions:
      - text: List API keys for subject {subject}.
        slots:
          subject: query.subject
      - text: List API keys for {subject}, including invalid ones ({include_invalid}).
        slots:
          subject: query.subject
          include_invalid: query.include_invalid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api_keys'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an API key
      effect: write
      questions:
      - How do I issue an API key to one of my users?
      - Can I give a new API key scopes and an expiration?
      instructions:
      - text: Create an API key named {name} for subject {subject}.
        slots:
          name: requestBody.name
          subject: requestBody.subject
      - text: Create API key {name} for {subject} expiring in {seconds_until_expiration} seconds.
        slots:
          name: requestBody.name
          subject: requestBody.subject
          seconds_until_expiration: requestBody.seconds_until_expiration
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api_keys/{apiKeyID}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve an API key by ID
      effect: read
      questions:
      - How do I look up the metadata of an API key by its ID?
      - What scopes and claims are on a specific API key?
      instructions:
      - text: Show API key {apiKeyID}.
        slots:
          apiKeyID: path.apiKeyID
      - text: Get the metadata of API key {apiKeyID}.
        slots:
          apiKeyID: path.apiKeyID
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api_keys/{apiKeyID}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an API key
      effect: destructive
      questions:
      - How do I permanently delete an API key record?
      - Can I remove an API key entirely instead of just revoking it?
      instructions:
      - text: Delete API key {apiKeyID}.
        slots:
          apiKeyID: path.apiKeyID
      - text: Permanently remove the API key record {apiKeyID}.
        slots:
          apiKeyID: path.apiKeyID
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api_keys/{apiKeyID}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update an API key's scopes or expiry
      effect: write
      questions:
      - How do I change the scopes on an existing API key?
      - Can I extend when an API key expires?
      instructions:
      - text: Update API key {apiKeyID} with scopes {scopes}.
        slots:
          apiKeyID: path.apiKeyID
          scopes: requestBody.scopes
      - text: Change the description of API key {apiKeyID} to {description}.
        slots:
          apiKeyID: path.apiKeyID
          description: requestBody.description
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api_keys/{apiKeyID}/secret'].get
  update:
    x-apievangelist-phrasing:
      intent: Reveal an API key's secret
      effect: read
      questions:
      - How do I retrieve the secret value of an API key?
      - Can I get the actual key string again after creating it?
      instructions:
      - text: Get the secret for API key {apiKeyID}.
        slots:
          apiKeyID: path.apiKeyID
      - text: Reveal the key string of API key {apiKeyID}.
        slots:
          apiKeyID: path.apiKeyID
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api_keys/{apiKeyID}/revoke'].post
  update:
    x-apievangelist-phrasing:
      intent: Revoke an API key
      effect: destructive
      questions:
      - How do I revoke a leaked API key so it stops working?
      - Can I record a reason when revoking an API key?
      instructions:
      - text: Revoke API key {apiKeyID}.
        slots:
          apiKeyID: path.apiKeyID
      - text: Revoke API key {apiKeyID} because {revocation_reason}.
        slots:
          apiKeyID: path.apiKeyID
          revocation_reason: requestBody.revocation_reason
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api_keys/verify'].post
  update:
    x-apievangelist-phrasing:
      intent: Verify an API key secret
      effect: read
      questions:
      - How do I check whether an API key presented to my service is valid?
      - What does verification return for an incoming API key secret?
      instructions:
      - text: Verify API key secret {secret}.
        slots:
          secret: requestBody.secret
      - text: Check whether incoming key {secret} is a valid API key.
        slots:
          secret: requestBody.secret
      method: generated
      generated: '2026-09-26'