# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Elastic Cloud Enterprise Iam Service API
  version: 1.0.0
extends: openapi/elk-stack-iamservice-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: 50
- target: $.paths['/organizations'].get
  update:
    x-apievangelist-phrasing:
      intent: List organizations I belong to
      effect: read
      questions:
      - Which Elastic Cloud organizations can my user see?
      - Is there a way to list every organization available to my account?
      instructions:
      - text: List the organizations available to me.
      - text: Show all organizations my current user can access.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/organizations/invitations/{invitation_token}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up an organization invitation by token
      effect: read
      questions:
      - What organization does this invitation token belong to?
      - Can I check the details of an invite before accepting it?
      instructions:
      - text: Show the organization invitation for token {invitation_token}.
        slots:
          invitation_token: path.invitation_token
      - text: Look up who invitation {invitation_token} is for and when it expires.
        slots:
          invitation_token: path.invitation_token
      method: generated
      generated: '2026-09-26'
- target: $.paths['/organizations/{organization_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an organization's details
      effect: read
      questions:
      - How do I fetch the details of a single organization by its id?
      - What contacts and settings are on my organization?
      instructions:
      - text: Get organization {organization_id}.
        slots:
          organization_id: path.organization_id
      - text: Show the name and contacts for organization {organization_id}.
        slots:
          organization_id: path.organization_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/organizations/{organization_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an organization's settings
      effect: write
      questions:
      - Can I rename my organization or change its billing contacts?
      - How do I restrict which email domains can receive organization notifications?
      instructions:
      - text: Rename organization {organization_id} to {name}.
        slots:
          organization_id: path.organization_id
          name: requestBody.name
      - text: Set the billing contacts of organization {organization_id} to {billing_contacts}.
        slots:
          organization_id: path.organization_id
          billing_contacts: requestBody.billing_contacts
      - text: Turn disk usage alerts {default_disk_usage_alerts_enabled} by default for organization {organization_id}.
        slots:
          organization_id: path.organization_id
          default_disk_usage_alerts_enabled: requestBody.default_disk_usage_alerts_enabled
      method: generated
      generated: '2026-09-26'
- target: $.paths['/organizations/{organization_id}/domains'].get
  update:
    x-apievangelist-phrasing:
      intent: List an organization's claimed domains
      effect: read
      questions:
      - Which email domains has my organization claimed?
      - Can I see the domain claims and their status for an organization?
      instructions:
      - text: List the domain claims for organization {organization_id}.
        slots:
          organization_id: path.organization_id
      - text: Show which domains organization {organization_id} has claimed.
        slots:
          organization_id: path.organization_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/organizations/{organization_id}/domains'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a domain claim from an organization
      effect: destructive
      questions:
      - How do I drop a domain my organization no longer owns?
      - Can I release a claimed domain from my organization?
      instructions:
      - text: Delete the domain claim {domain_claim_request} from organization {organization_id}.
        slots:
          organization_id: path.organization_id
          domain_claim_request: requestBody.domain_claim_request
      - text: Release domain {domain_claim_request} claimed by organization {organization_id}.
        slots:
          organization_id: path.organization_id
          domain_claim_request: requestBody.domain_claim_request
      method: generated
      generated: '2026-09-26'
- target: $.paths['/organizations/{organization_id}/domains/_generate_verification_code'].post
  update:
    x-apievangelist-phrasing:
      intent: Generate a domain ownership verification code
      effect: write
      questions:
      - How do I get the verification code to prove my organization owns a domain?
      - What value do I need to publish before a domain claim can be verified?
      instructions:
      - text: Generate a verification code for domain {domain_claim_request} in organization {organization_id}.
        slots:
          organization_id: path.organization_id
          domain_claim_request: requestBody.domain_claim_request
      - text: Start a domain claim challenge for {domain_claim_request} on organization {organization_id}.
        slots:
          organization_id: path.organization_id
          domain_claim_request: requestBody.domain_claim_request
      method: generated
      generated: '2026-09-26'
- target: $.paths['/organizations/{organization_id}/domains/_verify'].post
  update:
    x-apievangelist-phrasing:
      intent: Verify a domain claim challenge
      effect: write
      questions:
      - I published the verification code, how do I complete the domain claim?
      - Can I check that my organization's domain challenge now passes?
      instructions:
      - text: Verify the domain claim for {domain_claim_request} in organization {organization_id}.
        slots:
          organization_id: path.organization_id
          domain_claim_request: requestBody.domain_claim_request
      - text: Complete the ownership check for domain {domain_claim_request} on organization {organization_id}.
        slots:
          organization_id: path.organization_id
          domain_claim_request: requestBody.domain_claim_request
      method: generated
      generated: '2026-09-26'
- target: $.paths['/organizations/{organization_id}/idp'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an organization's identity provider setup
      effect: read
      questions:
      - Is SAML single sign-on configured for my organization?
      - What identity provider settings does my organization currently use?
      instructions:
      - text: Show the IdP configuration for organization {organization_id}.
        slots:
          organization_id: path.organization_id
      - text: Check whether organization {organization_id} has SSO enabled.
        slots:
          organization_id: path.organization_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/organizations/{organization_id}/idp'].put
  update:
    x-apievangelist-phrasing:
      intent: Configure SAML SSO for an organization
      effect: write
      questions:
      - How do I connect my company's SAML identity provider to my Elastic organization?
      - Can I require a login identifier prefix when setting up organization SSO?
      instructions:
      - text: Set up the SAML IdP {saml_idp} for organization {organization_id} with login prefix {login_identifier_prefix}.
        slots:
          organization_id: path.organization_id
          saml_idp: requestBody.saml_idp
          login_identifier_prefix: requestBody.login_identifier_prefix
      - text: Configure SSO for organization {organization_id} and set enabled to {enabled}.
        slots:
          organization_id: path.organization_id
          enabled: requestBody.enabled
      method: generated
      generated: '2026-09-26'
- target: $.paths['/organizations/{organization_id}/idp'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove an organization's identity provider
      effect: destructive
      questions:
      - How do I turn off SAML SSO entirely for my organization?
      - Can I tear down the identity provider we configured for the organization?
      instructions:
      - text: Tear down the IdP for organization {organization_id}.
        slots:
          organization_id: path.organization_id
      - text: Remove SAML single sign-on from organization {organization_id}.
        slots:
          organization_id: path.organization_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/organizations/{organization_id}/idp/metadata.xml'].get
  update:
    x-apievangelist-phrasing:
      intent: Download the organization's SAML SP metadata
      effect: read
      questions:
      - Where do I get the metadata.xml my identity provider needs for Elastic SSO?
      - Can I download the service provider SAML metadata for my organization?
      instructions:
      - text: Download the SAML metadata.xml for organization {organization_id}.
        slots:
          organization_id: path.organization_id
      - text: Get the service provider metadata to give our IdP for organization {organization_id}.
        slots:
          organization_id: path.organization_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/organizations/{organization_id}/invitations'].get
  update:
    x-apievangelist-phrasing:
      intent: List pending organization invitations
      effect: read
      questions:
      - Who has been invited to my organization but hasn't joined yet?
      - Can I see all open invitations for an organization?
      instructions:
      - text: List open invitations for organization {organization_id}.
        slots:
          organization_id: path.organization_id
      - text: Show the pending invites to organization {organization_id}.
        slots:
          organization_id: path.organization_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/organizations/{organization_id}/invitations'].post
  update:
    x-apievangelist-phrasing:
      intent: Invite people to an organization
      effect: write
      questions:
      - How do I invite teammates by email to my Elastic Cloud organization?
      - Can I set how long an organization invitation stays valid?
      - Can I give invited users a role when I send the invite?
      instructions:
      - text: Invite {emails} to organization {organization_id}.
        slots:
          organization_id: path.organization_id
          emails: requestBody.emails
      - text: Invite {emails} to organization {organization_id} with an invitation that expires in {expires_in}.
        slots:
          organization_id: path.organization_id
          emails: requestBody.emails
          expires_in: requestBody.expires_in
      - text: Send organization {organization_id} invites to {emails} with role assignments {role_assignments}.
        slots:
          organization_id: path.organization_id
          emails: requestBody.emails
          role_assignments: requestBody.role_assignments
      method: generated
      generated: '2026-09-26'
- target: $.paths['/organizations/{organization_id}/invitations/{invitation_tokens}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Revoke organization invitations
      effect: destructive
      questions:
      - How do I cancel an invitation I sent by mistake?
      - Can I withdraw several organization invites at once?
      instructions:
      - text: Delete invitations {invitation_tokens} from organization {organization_id}.
        slots:
          organization_id: path.organization_id
          invitation_tokens: path.invitation_tokens
      - text: Cancel the pending invites {invitation_tokens} to organization {organization_id}.
        slots:
          organization_id: path.organization_id
          invitation_tokens: path.invitation_tokens
      method: generated
      generated: '2026-09-26'
- target: $.paths['/organizations/{organization_id}/members'].get
  update:
    x-apievangelist-phrasing:
      intent: List an organization's members
      effect: read
      questions:
      - Who are the current members of my organization?
      - Can I list every user belonging to an organization?
      instructions:
      - text: List the members of organization {organization_id}.
        slots:
          organization_id: path.organization_id
      - text: Show everyone who belongs to organization {organization_id}.
        slots:
          organization_id: path.organization_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/organizations/{organization_id}/members/{user_ids}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove members from an organization
      effect: destructive
      questions:
      - How do I remove a user from my organization?
      - Can I force-remove members even when the removal would otherwise be blocked?
      instructions:
      - text: Remove users {user_ids} from organization {organization_id}.
        slots:
          organization_id: path.organization_id
          user_ids: path.user_ids
      - text: Force the removal of members {user_ids} from organization {organization_id} with force {force}.
        slots:
          organization_id: path.organization_id
          user_ids: path.user_ids
          force: query.force
      method: generated
      generated: '2026-09-26'
- target: $.paths['/organizations/{organization_id}/role_mappings'].get
  update:
    x-apievangelist-phrasing:
      intent: Get SSO role mappings for an organization
      effect: read
      questions:
      - Which roles do users get when they sign in through our SSO?
      - Can I view all role mappings configured for my organization?
      instructions:
      - text: Show the role mappings for organization {organization_id}.
        slots:
          organization_id: path.organization_id
      - text: List how SSO groups map to roles in organization {organization_id}.
        slots:
          organization_id: path.organization_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/organizations/{organization_id}/role_mappings'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace all SSO role mappings
      effect: write
      questions:
      - How do I replace the full set of SSO role mappings for my organization?
      - Can I overwrite every role mapping in one request?
      instructions:
      - text: Replace the role mappings of organization {organization_id} with {mappings}.
        slots:
          organization_id: path.organization_id
          mappings: requestBody.mappings
      - text: Overwrite all SSO role assignments for organization {organization_id} using {mappings}.
        slots:
          organization_id: path.organization_id
          mappings: requestBody.mappings
      method: generated
      generated: '2026-09-26'
- target: $.paths['/organizations/{organization_id}/role_mappings'].post
  update:
    x-apievangelist-phrasing:
      intent: Add new SSO role mappings
      effect: write
      questions:
      - Can I add a role mapping without touching the existing ones?
      - How do I grant an extra role to SSO users from a new group?
      instructions:
      - text: Add role mappings {mappings} to organization {organization_id}.
        slots:
          organization_id: path.organization_id
          mappings: requestBody.mappings
      - text: Append the SSO mappings {mappings} to what organization {organization_id} already has.
        slots:
          organization_id: path.organization_id
          mappings: requestBody.mappings
      method: generated
      generated: '2026-09-26'
- target: $.paths['/organizations/{organization_id}/role_mappings'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete all SSO role mappings
      effect: destructive
      questions:
      - How do I clear every role mapping from my organization?
      - Can I wipe out all SSO role assignments at once?
      instructions:
      - text: Delete all role mappings in organization {organization_id}.
        slots:
          organization_id: path.organization_id
      - text: Clear every SSO role mapping from organization {organization_id}.
        slots:
          organization_id: path.organization_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/organizations/{organization_id}/role_mappings/{role_names}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete specific SSO role mappings by name
      effect: destructive
      questions:
      - Can I delete just one named role mapping and keep the others?
      - How do I remove a few role mappings by their names?
      instructions:
      - text: Delete role mappings {role_names} from organization {organization_id}.
        slots:
          organization_id: path.organization_id
          role_names: path.role_names
      - text: Remove only the mappings named {role_names} in organization {organization_id}.
        slots:
          organization_id: path.organization_id
          role_names: path.role_names
      method: generated
      generated: '2026-09-26'
- target: $.paths['/organizations/{organization_id}/role_mappings/{role_name}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update one SSO role mapping by name
      effect: write
      questions:
      - How do I edit a single existing role mapping?
      - Can I change what one named mapping grants without replacing the rest?
      instructions:
      - text: Update role mapping {role_name} in organization {organization_id} to {mapping}.
        slots:
          organization_id: path.organization_id
          role_name: path.role_name
          mapping: requestBody.mapping
      - text: Change the mapping named {role_name} for organization {organization_id}.
        slots:
          organization_id: path.organization_id
          role_name: path.role_name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/user'].get
  update:
    x-apievangelist-phrasing:
      intent: Get my own user profile
      effect: read
      questions:
      - Which user am I logged in as right now?
      - What does my own user profile contain?
      instructions:
      - text: Show my current user information.
      - text: Tell me who I'm authenticated as.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/user'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update my own user profile
      effect: write
      questions:
      - How do I change details on my own user account?
      - Can I edit my profile without admin access to other users?
      instructions:
      - text: Update my own user profile.
      - text: Save changes to the currently logged in user.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users'].get
  update:
    x-apievangelist-phrasing:
      intent: List all platform users
      effect: read
      questions:
      - What users exist in my Elastic Cloud Enterprise installation?
      - Can I include disabled accounts when listing users?
      instructions:
      - text: List all users.
      - text: List every user, including disabled ones when include_disabled is {include_disabled}.
        slots:
          include_disabled: query.include_disabled
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new platform user
      effect: write
      questions:
      - How do I add a new user account to the platform?
      - What security settings are required when creating a user?
      instructions:
      - text: Create user {user_name} with security settings {security}.
        slots:
          user_name: requestBody.user_name
          security: requestBody.security
      - text: Add a user named {user_name} with full name {full_name} and email {email}, security {security}.
        slots:
          user_name: requestBody.user_name
          full_name: requestBody.full_name
          email: requestBody.email
          security: requestBody.security
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/auth'].get
  update:
    x-apievangelist-phrasing:
      intent: Check my authentication status
      effect: read
      questions:
      - Do I currently have elevated permissions in my session?
      - Is a TOTP device available for my user?
      instructions:
      - text: Show my authentication information.
      - text: Check whether my session has elevated permissions and a TOTP device.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/auth/_login'].post
  update:
    x-apievangelist-phrasing:
      intent: Log in with a username and password
      effect: write
      questions:
      - How do I authenticate to ECE with my username and password?
      - What do I get back after logging in to the platform API?
      instructions:
      - text: Log in as {username} with password {password}.
        slots:
          username: requestBody.username
          password: requestBody.password
      - text: Authenticate user {username} using {password} and login state {login_state}.
        slots:
          username: requestBody.username
          password: requestBody.password
          login_state: requestBody.login_state
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/auth/_logout'].post
  update:
    x-apievangelist-phrasing:
      intent: Log out and end my session
      effect: destructive
      questions:
      - How do I end my current ECE session?
      - Can I destroy my login session through the API?
      instructions:
      - text: Log me out.
      - text: End my current session now.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/auth/_refresh'].post
  update:
    x-apievangelist-phrasing:
      intent: Refresh my authentication token
      effect: write
      questions:
      - My token is about to expire, how do I get a fresh one?
      - Can I renew my auth token without logging in again?
      instructions:
      - text: Refresh my authentication token.
      - text: Issue me a new auth token for the current session.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/auth/keys'].get
  update:
    x-apievangelist-phrasing:
      intent: List API keys I can see
      effect: read
      questions:
      - Which API keys have I created?
      - How do I page through a long list of API keys?
      instructions:
      - text: List my API keys.
      - text: Show the next page of API keys starting from {next_page}.
        slots:
          next_page: query.next_page
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/auth/keys'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an API key
      effect: write
      questions:
      - How do I generate a new API key for automation?
      - Can I give an API key an expiration and specific roles?
      instructions:
      - text: Create an API key described as {description}.
        slots:
          description: requestBody.description
      - text: Create an API key {description} that expires in {expiration}.
        slots:
          description: requestBody.description
          expiration: requestBody.expiration
      - text: Create API key {description} with role assignments {role_assignments}.
        slots:
          description: requestBody.description
          role_assignments: requestBody.role_assignments
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/auth/keys'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete several of my API keys
      effect: destructive
      questions:
      - Can I invalidate a batch of my API keys in one call?
      - How do I revoke multiple API keys at once?
      instructions:
      - text: Delete API keys {keys}.
        slots:
          keys: requestBody.keys
      - text: Invalidate the keys {keys} in a single request.
        slots:
          keys: requestBody.keys
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/auth/keys/_all'].get
  update:
    x-apievangelist-phrasing:
      intent: List API keys across all users (deprecated)
      effect: read
      questions:
      - Is there a way to see API keys for every user on the platform?
      - Which endpoint shows all users' API key metadata, even though it's deprecated?
      instructions:
      - text: List API key metadata for all users using the deprecated endpoint.
      - text: Show every user's API keys across the platform.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/auth/keys/_all'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete API keys belonging to multiple users
      effect: destructive
      questions:
      - How do I revoke API keys owned by several different users?
      - Can an admin invalidate keys for many users in one request?
      instructions:
      - text: 'Delete these API keys across users: {user_api_keys}.'
        slots:
          user_api_keys: requestBody.user_api_keys
      - text: Invalidate the per-user keys {user_api_keys} for multiple users.
        slots:
          user_api_keys: requestBody.user_api_keys
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/auth/keys/{api_key_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one of my API keys
      effect: read
      questions:
      - What are the details of a specific API key I own?
      - When does one particular API key of mine expire?
      instructions:
      - text: Get API key {api_key_id}.
        slots:
          api_key_id: path.api_key_id
      - text: Show metadata for my API key {api_key_id}.
        slots:
          api_key_id: path.api_key_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/auth/keys/{api_key_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete one of my API keys
      effect: destructive
      questions:
      - How do I revoke a single API key I created?
      - Can I invalidate one leaked key without touching the others?
      instructions:
      - text: Delete API key {api_key_id}.
        slots:
          api_key_id: path.api_key_id
      - text: Revoke my key {api_key_id} immediately.
        slots:
          api_key_id: path.api_key_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/auth/methods'].get
  update:
    x-apievangelist-phrasing:
      intent: List available authentication methods
      effect: read
      questions:
      - Which login methods does the platform support?
      - Is SAML available as a sign-in option here?
      instructions:
      - text: List the available authentication methods.
      - text: Show which ways users can sign in.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/auth/saml/_callback'].post
  update:
    x-apievangelist-phrasing:
      intent: Complete SAML sign-in from an IdP response
      effect: write
      questions:
      - What endpoint receives the SAML response from the identity provider?
      - How is a user authenticated once the IdP posts back a SAMLResponse?
      instructions:
      - text: Authenticate using SAML response {SAMLResponse}.
        slots:
          SAMLResponse: requestBody.SAMLResponse
      - text: Process IdP callback {SAMLResponse} with relay state {RelayState}.
        slots:
          SAMLResponse: requestBody.SAMLResponse
          RelayState: requestBody.RelayState
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/auth/saml/_init'].get
  update:
    x-apievangelist-phrasing:
      intent: Start SAML single sign-on
      effect: read
      questions:
      - How do I kick off the SAML SSO redirect to our identity provider?
      - Can I pick a specific SAML realm when starting sign-on?
      instructions:
      - text: Initiate SAML sign-on.
      - text: Start SAML SSO against realm {realm} with state {state}.
        slots:
          realm: query.realm
          state: query.state
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{user_id}/auth/keys'].get
  update:
    x-apievangelist-phrasing:
      intent: List a user's API keys
      effect: read
      questions:
      - Which API keys has a particular user created?
      - Can an admin see all keys belonging to one user?
      instructions:
      - text: List API keys created by user {user_id}.
        slots:
          user_id: path.user_id
      - text: Show key metadata for every key owned by {user_id}.
        slots:
          user_id: path.user_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{user_id}/auth/keys'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete all API keys for a user
      effect: destructive
      questions:
      - How do I revoke every API key an offboarded user created?
      - Can I wipe all of one user's keys in one step?
      instructions:
      - text: Delete all API keys for user {user_id}.
        slots:
          user_id: path.user_id
      - text: Invalidate every key owned by {user_id}.
        slots:
          user_id: path.user_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{user_id}/auth/keys/{api_key_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a specific API key of a user
      effect: read
      questions:
      - What does one particular key belonging to another user look like?
      - Can an admin inspect a single key for a named user?
      instructions:
      - text: Get API key {api_key_id} of user {user_id}.
        slots:
          user_id: path.user_id
          api_key_id: path.api_key_id
      - text: Show metadata for user {user_id}'s key {api_key_id}.
        slots:
          user_id: path.user_id
          api_key_id: path.api_key_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{user_id}/auth/keys/{api_key_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a specific API key of a user
      effect: destructive
      questions:
      - How do I revoke one key belonging to another user?
      - Can an admin invalidate a single key for a named user?
      instructions:
      - text: Delete API key {api_key_id} belonging to user {user_id}.
        slots:
          user_id: path.user_id
          api_key_id: path.api_key_id
      - text: Revoke user {user_id}'s key {api_key_id}.
        slots:
          user_id: path.user_id
          api_key_id: path.api_key_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{user_id}/role_assignments'].post
  update:
    x-apievangelist-phrasing:
      intent: Grant roles to a user
      effect: write
      questions:
      - How do I give a user a deployment or organization role?
      - Can I assign platform-level roles to a user?
      instructions:
      - text: Add deployment role assignments {deployment} to user {user_id}.
        slots:
          user_id: path.user_id
          deployment: requestBody.deployment
      - text: Grant user {user_id} the organization roles {organization}.
        slots:
          user_id: path.user_id
          organization: requestBody.organization
      - text: Give user {user_id} platform roles {platform}.
        slots:
          user_id: path.user_id
          platform: requestBody.platform
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{user_id}/role_assignments'].delete
  update:
    x-apievangelist-phrasing:
      intent: Revoke roles from a user
      effect: destructive
      questions:
      - How do I take a deployment role away from a user?
      - Can I force-remove a user's role assignments?
      instructions:
      - text: Remove deployment role assignments {deployment} from user {user_id}.
        slots:
          user_id: path.user_id
          deployment: requestBody.deployment
      - text: Revoke organization roles {organization} from user {user_id} with force {force}.
        slots:
          user_id: path.user_id
          organization: requestBody.organization
          force: query.force
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{user_name}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user by username
      effect: read
      questions:
      - What details are stored for a given username?
      - Can I look up one user account by name?
      instructions:
      - text: Get user {user_name}.
        slots:
          user_name: path.user_name
      - text: Show the account details for {user_name}.
        slots:
          user_name: path.user_name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{user_name}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a user account
      effect: destructive
      questions:
      - How do I permanently remove a user account?
      - Can I delete a user who has left the team?
      instructions:
      - text: Delete user {user_name}.
        slots:
          user_name: path.user_name
      - text: Remove the account {user_name} from the platform.
        slots:
          user_name: path.user_name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{user_name}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update another user's account
      effect: write
      questions:
      - How do I change details on an existing user account?
      - Can an admin edit someone else's user profile?
      instructions:
      - text: Update user {user_name}.
        slots:
          user_name: path.user_name
      - text: Edit the account settings for {user_name}.
        slots:
          user_name: path.user_name
      method: generated
      generated: '2026-09-26'