# 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 Platform Configuration Security API
  version: 1.0.0
extends: openapi/elk-stack-platformconfigurationsecurity-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: 22
- target: $.paths['/platform/configuration/security/deployment'].get
  update:
    x-apievangelist-phrasing:
      intent: View the platform security deployment
      effect: read
      questions:
      - What does the current security deployment for my Elastic Cloud Enterprise platform look like?
      - Is a security deployment already set up on this installation?
      instructions:
      - text: Show the current security deployment.
      - text: Get the platform's security deployment configuration.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/platform/configuration/security/deployment'].put
  update:
    x-apievangelist-phrasing:
      intent: Update the platform security deployment
      effect: write
      questions:
      - Can I change the version or topology of the existing security deployment?
      - How do I resize the security deployment that backs platform authentication?
      instructions:
      - text: Update the security deployment to version {version}.
        slots:
          version: requestBody.version
      - text: Change the existing security deployment topology to {topology}.
        slots:
          topology: requestBody.topology
      method: generated
      generated: '2026-09-26'
- target: $.paths['/platform/configuration/security/deployment'].post
  update:
    x-apievangelist-phrasing:
      intent: Create the platform security deployment
      effect: write
      questions:
      - How do I set up a security deployment for the first time on my platform?
      - What name and version can I give a new security deployment?
      instructions:
      - text: Create a security deployment named {name}.
        slots:
          name: requestBody.name
      - text: Set up a new security deployment {name} on version {version}.
        slots:
          name: requestBody.name
          version: requestBody.version
      method: generated
      generated: '2026-09-26'
- target: $.paths['/platform/configuration/security/enrollment-tokens'].get
  update:
    x-apievangelist-phrasing:
      intent: List active enrollment tokens
      effect: read
      questions:
      - Which enrollment tokens are currently active for adding hosts to the platform?
      - Can I review all outstanding runner enrollment tokens?
      instructions:
      - text: List all active enrollment tokens.
      - text: Show outstanding enrollment tokens for new hosts.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/platform/configuration/security/enrollment-tokens'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an enrollment token
      effect: write
      questions:
      - How do I generate a token so a new host can join my installation with certain roles?
      - Can an enrollment token expire after a set number of seconds, or be persistent?
      instructions:
      - text: Create an enrollment token with persistent set to {persistent}.
        slots:
          persistent: requestBody.persistent
      - text: Generate an enrollment token for roles {roles} valid for {validity_in_seconds} seconds, persistent {persistent}.
        slots:
          roles: requestBody.roles
          validity_in_seconds: requestBody.validity_in_seconds
          persistent: requestBody.persistent
      method: generated
      generated: '2026-09-26'
- target: $.paths['/platform/configuration/security/enrollment-tokens/{token}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Revoke an enrollment token
      effect: destructive
      questions:
      - How can I revoke an enrollment token that leaked?
      - Does deleting an enrollment token stop it from being used immediately?
      instructions:
      - text: Revoke enrollment token {token}.
        slots:
          token: path.token
      - text: Delete the enrollment token {token} so no more hosts can use it.
        slots:
          token: path.token
      method: generated
      generated: '2026-09-26'
- target: $.paths['/platform/configuration/security/realms'].get
  update:
    x-apievangelist-phrasing:
      intent: List security realm configurations
      effect: read
      questions:
      - Which authentication realms, like LDAP, SAML or Active Directory, are configured?
      - In what order are my security realms evaluated?
      instructions:
      - text: List every configured security realm.
      - text: Show all realm configurations across LDAP, SAML and Active Directory.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/platform/configuration/security/realms/_reorder'].post
  update:
    x-apievangelist-phrasing:
      intent: Reorder security realms
      effect: write
      questions:
      - Can I change which authentication realm is tried first?
      - How is the evaluation order of security realms set?
      instructions:
      - text: Reorder the security realms to {realms}.
        slots:
          realms: requestBody.realms
      - text: Set realm evaluation order as {realms}.
        slots:
          realms: requestBody.realms
      method: generated
      generated: '2026-09-26'
- target: $.paths['/platform/configuration/security/realms/active-directory'].post
  update:
    x-apievangelist-phrasing:
      intent: Add an Active Directory realm
      effect: write
      questions:
      - How do I let users sign in to the platform with Active Directory?
      - Can an Active Directory realm bind anonymously instead of with a bind DN?
      instructions:
      - text: Create Active Directory realm {id} named {name} for domain {domain_name} at {urls}, bind anonymously {bind_anonymously}.
        slots:
          id: requestBody.id
          name: requestBody.name
          domain_name: requestBody.domain_name
          urls: requestBody.urls
          bind_anonymously: requestBody.bind_anonymously
      - text: Add an AD realm {id} called {name} on domain {domain_name}, servers {urls}, anonymous bind {bind_anonymously}, bind DN {bind_dn}.
        slots:
          id: requestBody.id
          name: requestBody.name
          domain_name: requestBody.domain_name
          urls: requestBody.urls
          bind_anonymously: requestBody.bind_anonymously
          bind_dn: requestBody.bind_dn
      method: generated
      generated: '2026-09-26'
- target: $.paths['/platform/configuration/security/realms/active-directory/{realm_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an Active Directory realm
      effect: read
      questions:
      - What domain and server URLs does one Active Directory realm use?
      - Can I view the role mappings on an Active Directory realm?
      instructions:
      - text: Show Active Directory realm {realm_id}.
        slots:
          realm_id: path.realm_id
      - text: Get the AD configuration for realm {realm_id}.
        slots:
          realm_id: path.realm_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/platform/configuration/security/realms/active-directory/{realm_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an Active Directory realm
      effect: write
      questions:
      - How do I change the domain controllers an existing Active Directory realm points at?
      - Can I disable an Active Directory realm without deleting it?
      instructions:
      - text: 'Update AD realm {realm_id}: id {id}, name {name}, domain {domain_name}, URLs {urls}, anonymous bind {bind_anonymously}.'
        slots:
          realm_id: path.realm_id
          id: requestBody.id
          name: requestBody.name
          domain_name: requestBody.domain_name
          urls: requestBody.urls
          bind_anonymously: requestBody.bind_anonymously
      - text: Set enabled {enabled} on Active Directory realm {realm_id} ({id}, {name}, {domain_name}, {urls}, bind anonymously {bind_anonymously}).
        slots:
          realm_id: path.realm_id
          enabled: requestBody.enabled
          id: requestBody.id
          name: requestBody.name
          domain_name: requestBody.domain_name
          urls: requestBody.urls
          bind_anonymously: requestBody.bind_anonymously
      method: generated
      generated: '2026-09-26'
- target: $.paths['/platform/configuration/security/realms/active-directory/{realm_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an Active Directory realm
      effect: destructive
      questions:
      - Can I remove an Active Directory login realm from the platform?
      - Do I need a version number to safely delete an AD realm?
      instructions:
      - text: Delete Active Directory realm {realm_id}.
        slots:
          realm_id: path.realm_id
      - text: Remove AD realm {realm_id} at version {version}.
        slots:
          realm_id: path.realm_id
          version: query.version
      method: generated
      generated: '2026-09-26'
- target: $.paths['/platform/configuration/security/realms/ldap'].post
  update:
    x-apievangelist-phrasing:
      intent: Add an LDAP realm
      effect: write
      questions:
      - How do I connect platform login to our LDAP directory?
      - Can an LDAP realm use user DN templates instead of searching for users?
      instructions:
      - text: Create LDAP realm {id} named {name} at {urls}, bind type {bind_type}, anonymous bind {bind_anonymously}.
        slots:
          id: requestBody.id
          name: requestBody.name
          urls: requestBody.urls
          bind_type: requestBody.bind_type
          bind_anonymously: requestBody.bind_anonymously
      - text: Add LDAP realm {id} ({name}) on {urls} with bind type {bind_type}, anonymous {bind_anonymously}, DN templates {user_dn_templates}.
        slots:
          id: requestBody.id
          name: requestBody.name
          urls: requestBody.urls
          bind_type: requestBody.bind_type
          bind_anonymously: requestBody.bind_anonymously
          user_dn_templates: requestBody.user_dn_templates
      method: generated
      generated: '2026-09-26'
- target: $.paths['/platform/configuration/security/realms/ldap/{realm_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an LDAP realm
      effect: read
      questions:
      - What LDAP servers and group search settings does a given realm use?
      - Can I inspect a single LDAP realm's configuration?
      instructions:
      - text: Show LDAP realm {realm_id}.
        slots:
          realm_id: path.realm_id
      - text: Get the LDAP configuration of realm {realm_id}.
        slots:
          realm_id: path.realm_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/platform/configuration/security/realms/ldap/{realm_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an LDAP realm
      effect: write
      questions:
      - How do I change the bind credentials or servers of an existing LDAP realm?
      - Can I update the group attribute an LDAP realm maps roles from?
      instructions:
      - text: 'Update LDAP realm {realm_id}: id {id}, name {name}, URLs {urls}, bind type {bind_type}, anonymous {bind_anonymously}.'
        slots:
          realm_id: path.realm_id
          id: requestBody.id
          name: requestBody.name
          urls: requestBody.urls
          bind_type: requestBody.bind_type
          bind_anonymously: requestBody.bind_anonymously
      - text: Change group attribute to {user_group_attribute} on LDAP realm {realm_id} ({id}, {name}, {urls}, {bind_type}, anon {bind_anonymously}).
        slots:
          realm_id: path.realm_id
          user_group_attribute: requestBody.user_group_attribute
          id: requestBody.id
          name: requestBody.name
          urls: requestBody.urls
          bind_type: requestBody.bind_type
          bind_anonymously: requestBody.bind_anonymously
      method: generated
      generated: '2026-09-26'
- target: $.paths['/platform/configuration/security/realms/ldap/{realm_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an LDAP realm
      effect: destructive
      questions:
      - Can I remove an LDAP realm we no longer use for sign-in?
      - Is a version check supported when deleting an LDAP realm?
      instructions:
      - text: Delete LDAP realm {realm_id}.
        slots:
          realm_id: path.realm_id
      - text: Remove LDAP realm {realm_id} at version {version}.
        slots:
          realm_id: path.realm_id
          version: query.version
      method: generated
      generated: '2026-09-26'
- target: $.paths['/platform/configuration/security/realms/saml'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a SAML realm
      effect: write
      questions:
      - How do I enable single sign-on to the platform through a SAML identity provider?
      - Can a SAML realm force re-authentication or sign its SAML messages?
      instructions:
      - text: Create SAML realm {id} named {name} with IdP {idp}, SP {sp} and attributes {attributes}.
        slots:
          id: requestBody.id
          name: requestBody.name
          idp: requestBody.idp
          sp: requestBody.sp
          attributes: requestBody.attributes
      - text: Add SAML SSO realm {id} ({name}) using IdP {idp}, service provider {sp}, attribute mapping {attributes}, force_authn {force_authn}.
        slots:
          id: requestBody.id
          name: requestBody.name
          idp: requestBody.idp
          sp: requestBody.sp
          attributes: requestBody.attributes
          force_authn: requestBody.force_authn
      method: generated
      generated: '2026-09-26'
- target: $.paths['/platform/configuration/security/realms/saml/{realm_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a SAML realm
      effect: read
      questions:
      - What identity provider and attribute mappings does a given SAML realm use?
      - Can I check a single SAML realm's settings?
      instructions:
      - text: Show SAML realm {realm_id}.
        slots:
          realm_id: path.realm_id
      - text: Get the SAML configuration for realm {realm_id}.
        slots:
          realm_id: path.realm_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/platform/configuration/security/realms/saml/{realm_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a SAML realm
      effect: write
      questions:
      - How do I update the identity provider metadata on an existing SAML realm?
      - Can I change role mappings on a SAML realm I already configured?
      instructions:
      - text: 'Update SAML realm {realm_id}: id {id}, name {name}, IdP {idp}, SP {sp}, attributes {attributes}.'
        slots:
          realm_id: path.realm_id
          id: requestBody.id
          name: requestBody.name
          idp: requestBody.idp
          sp: requestBody.sp
          attributes: requestBody.attributes
      - text: Set role mappings {role_mappings} on SAML realm {realm_id} ({id}, {name}, {idp}, {sp}, {attributes}).
        slots:
          realm_id: path.realm_id
          role_mappings: requestBody.role_mappings
          id: requestBody.id
          name: requestBody.name
          idp: requestBody.idp
          sp: requestBody.sp
          attributes: requestBody.attributes
      method: generated
      generated: '2026-09-26'
- target: $.paths['/platform/configuration/security/realms/saml/{realm_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a SAML realm
      effect: destructive
      questions:
      - Can I remove a SAML single sign-on realm from the platform?
      - What version do I pass when deleting a SAML realm?
      instructions:
      - text: Delete SAML realm {realm_id}.
        slots:
          realm_id: path.realm_id
      - text: Remove SAML realm {realm_id} at version {version}.
        slots:
          realm_id: path.realm_id
          version: query.version
      method: generated
      generated: '2026-09-26'
- target: $.paths['/platform/configuration/security/tls/{service_name}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a service's TLS certificate chain
      effect: read
      questions:
      - Which TLS certificate is the platform's proxy or admin console serving?
      - Can I check the certificate chain installed for a platform service?
      instructions:
      - text: Show the TLS certificate for service {service_name}.
        slots:
          service_name: path.service_name
      - text: Get the certificate chain in use by {service_name}.
        slots:
          service_name: path.service_name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/platform/configuration/security/tls/{service_name}'].post
  update:
    x-apievangelist-phrasing:
      intent: Set a service's TLS certificate chain
      effect: write
      questions:
      - How do I install a new TLS certificate for a platform service?
      - Can I replace an expiring certificate chain on the proxy?
      instructions:
      - text: Upload a new TLS certificate chain for service {service_name}.
        slots:
          service_name: path.service_name
      - text: Replace the certificate on {service_name} with this chain.
        slots:
          service_name: path.service_name
      method: generated
      generated: '2026-09-26'