# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Clerk Backend Machines API
  version: 1.0.0
extends: openapi/clerk-com-machines-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: 9
- target: $.paths['/machines'].get
  update:
    x-apievangelist-phrasing:
      intent: List machines in an instance
      effect: read
      questions:
      - Which machines have been set up for machine-to-machine auth in my instance?
      - Can I search machines by name and sort the results?
      instructions:
      - text: List all machines in my instance.
      - text: Search machines matching {query}.
        slots:
          query: query.query
      method: generated
      generated: '2026-09-26'
- target: $.paths['/machines'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a machine identity
      effect: write
      questions:
      - How do I register a new service as a machine for M2M tokens?
      - Can I set a default token lifetime when creating a machine?
      instructions:
      - text: Create a machine named {name}.
        slots:
          name: requestBody.name
      - text: Create machine {name} with default token TTL {default_token_ttl}.
        slots:
          name: requestBody.name
          default_token_ttl: requestBody.default_token_ttl
      method: generated
      generated: '2026-09-26'
- target: $.paths['/machines/{machine_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve a machine
      effect: read
      questions:
      - How do I see the details of one machine?
      - What is the configured default token TTL on a given machine?
      instructions:
      - text: Show machine {machine_id}.
        slots:
          machine_id: path.machine_id
      - text: Get the details of machine {machine_id}.
        slots:
          machine_id: path.machine_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/machines/{machine_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a machine
      effect: destructive
      questions:
      - How do I remove a machine that is no longer used?
      - Can I delete a machine identity for a decommissioned service?
      instructions:
      - text: Delete machine {machine_id}.
        slots:
          machine_id: path.machine_id
      - text: Remove decommissioned machine {machine_id}.
        slots:
          machine_id: path.machine_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/machines/{machine_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Rename or reconfigure a machine
      effect: write
      questions:
      - How do I rename an existing machine?
      - Can I change a machine's default token lifetime after creating it?
      instructions:
      - text: Rename machine {machine_id} to {name}.
        slots:
          machine_id: path.machine_id
          name: requestBody.name
      - text: Set the default token TTL of machine {machine_id} to {default_token_ttl}.
        slots:
          machine_id: path.machine_id
          default_token_ttl: requestBody.default_token_ttl
      method: generated
      generated: '2026-09-26'
- target: $.paths['/machines/{machine_id}/secret_key'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a machine's secret key
      effect: read
      questions:
      - Where do I find the secret key for a machine so my service can authenticate?
      - How do I read back the current secret of a machine?
      instructions:
      - text: Get the secret key for machine {machine_id}.
        slots:
          machine_id: path.machine_id
      - text: Show the current secret of machine {machine_id}.
        slots:
          machine_id: path.machine_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/machines/{machine_id}/secret_key/rotate'].post
  update:
    x-apievangelist-phrasing:
      intent: Rotate a machine's secret key
      effect: write
      questions:
      - How do I rotate a machine secret without breaking services immediately?
      - How long does the previous machine secret keep working after rotation?
      instructions:
      - text: Rotate the secret key of machine {machine_id}, keeping the old one valid for {previous_token_ttl} seconds.
        slots:
          machine_id: path.machine_id
          previous_token_ttl: requestBody.previous_token_ttl
      - text: Issue a fresh secret for machine {machine_id} with a {previous_token_ttl}-second grace period for the old one.
        slots:
          machine_id: path.machine_id
          previous_token_ttl: requestBody.previous_token_ttl
      method: generated
      generated: '2026-09-26'
- target: $.paths['/machines/{machine_id}/scopes'].post
  update:
    x-apievangelist-phrasing:
      intent: Allow one machine to access another
      effect: write
      questions:
      - How do I let one machine call another machine?
      - Is there a limit on how many scopes a machine can have?
      instructions:
      - text: Allow machine {machine_id} to access machine {to_machine_id}.
        slots:
          machine_id: path.machine_id
          to_machine_id: requestBody.to_machine_id
      - text: Grant machine {machine_id} a scope to call {to_machine_id}.
        slots:
          machine_id: path.machine_id
          to_machine_id: requestBody.to_machine_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/machines/{machine_id}/scopes/{other_machine_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove one machine's access to another
      effect: destructive
      questions:
      - How do I stop a machine from calling another machine?
      - Can I revoke a machine-to-machine scope between two services?
      instructions:
      - text: Remove machine {machine_id}'s access to machine {other_machine_id}.
        slots:
          machine_id: path.machine_id
          other_machine_id: path.other_machine_id
      - text: Delete the scope letting {machine_id} call {other_machine_id}.
        slots:
          machine_id: path.machine_id
          other_machine_id: path.other_machine_id
      method: generated
      generated: '2026-09-26'