# 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 Manage mTLS Identity Providers API
  version: 1.0.0
extends: openapi/here-manage-mtls-identity-providers-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['/realms/{realm}/mtlsIdentityProviders'].get
  update:
    x-apievangelist-phrasing:
      intent: List mTLS identity providers in a realm
      effect: read
      questions:
      - Which mTLS identity providers are configured for my HERE realm?
      - Are any certificate authorities trusted for mutual TLS in our organization?
      instructions:
      - text: List the mTLS identity providers in realm {realm}.
        slots:
          realm: path.realm
      - text: Show all trusted certificate authorities configured for mTLS in realm {realm}.
        slots:
          realm: path.realm
      method: generated
      generated: '2026-09-26'
- target: $.paths['/realms/{realm}/mtlsIdentityProviders'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an mTLS identity provider
      effect: write
      questions:
      - How do I let devices authenticate with client certificates from my own CA?
      - What do I need to register a certificate authority as an mTLS identity provider?
      instructions:
      - text: Create an mTLS identity provider named {name} in realm {realm} with CA chain {certificateChainPemContent}.
        slots:
          name: requestBody.name
          realm: path.realm
          certificateChainPemContent: requestBody.certificateChainPemContent
      - text: 'Trust this PEM certificate chain for mTLS in realm {realm} as {name}: {certificateChainPemContent}.'
        slots:
          realm: path.realm
          name: requestBody.name
          certificateChainPemContent: requestBody.certificateChainPemContent
      method: generated
      generated: '2026-09-26'
- target: $.paths['/realms/{realm}/mtlsIdentityProviders/{mtlsIdentityProvider}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an mTLS identity provider
      effect: read
      questions:
      - What certificate authority is behind a specific mTLS identity provider?
      - Can I view the configuration of one mTLS identity provider?
      instructions:
      - text: Get mTLS identity provider {mtlsIdentityProvider} in realm {realm}.
        slots:
          mtlsIdentityProvider: path.mtlsIdentityProvider
          realm: path.realm
      - text: Show details of mTLS provider {mtlsIdentityProvider} for realm {realm}.
        slots:
          mtlsIdentityProvider: path.mtlsIdentityProvider
          realm: path.realm
      method: generated
      generated: '2026-09-26'
- target: $.paths['/realms/{realm}/mtlsIdentityProviders/{mtlsIdentityProvider}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove an mTLS identity provider
      effect: destructive
      questions:
      - How do I stop trusting a certificate authority for mTLS in my realm?
      - Can an mTLS identity provider be deleted?
      instructions:
      - text: Delete mTLS identity provider {mtlsIdentityProvider} from realm {realm}.
        slots:
          mtlsIdentityProvider: path.mtlsIdentityProvider
          realm: path.realm
      - text: Remove the trusted CA {mtlsIdentityProvider} from realm {realm}.
        slots:
          mtlsIdentityProvider: path.mtlsIdentityProvider
          realm: path.realm
      method: generated
      generated: '2026-09-26'
- target: $.paths['/realms/{realm}/mtlsIdentityProviders/{mtlsIdentityProvider}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update an mTLS identity provider's CA chain
      effect: write
      questions:
      - How do I rotate the certificate chain on an existing mTLS identity provider?
      - Can I rename an mTLS identity provider?
      instructions:
      - text: Replace the CA chain of mTLS provider {mtlsIdentityProvider} in realm {realm} with {certificateChainPemContent} and name it {name}.
        slots:
          mtlsIdentityProvider: path.mtlsIdentityProvider
          realm: path.realm
          certificateChainPemContent: requestBody.certificateChainPemContent
          name: requestBody.name
      - text: Rename existing mTLS provider {mtlsIdentityProvider} in realm {realm} to {name}, keeping chain {certificateChainPemContent}.
        slots:
          mtlsIdentityProvider: path.mtlsIdentityProvider
          realm: path.realm
          name: requestBody.name
          certificateChainPemContent: requestBody.certificateChainPemContent
      method: generated
      generated: '2026-09-26'
- target: $.paths['/realms/{realm}/mtlsIdentityProviders/{mtlsIdentityProvider}/authenticators'].get
  update:
    x-apievangelist-phrasing:
      intent: List authenticators for an mTLS identity provider
      effect: read
      questions:
      - Which mTLS authenticator checks certificates for a given identity provider?
      - How many authenticators does an mTLS identity provider have?
      instructions:
      - text: List mTLS authenticators for identity provider {mtlsIdentityProvider} in realm {realm}.
        slots:
          mtlsIdentityProvider: path.mtlsIdentityProvider
          realm: path.realm
      - text: Show the authenticator configured on mTLS provider {mtlsIdentityProvider} in realm {realm}.
        slots:
          mtlsIdentityProvider: path.mtlsIdentityProvider
          realm: path.realm
      method: generated
      generated: '2026-09-26'
- target: $.paths['/realms/{realm}/mtlsIdentityProviders/{mtlsIdentityProvider}/authenticators/{mtlsAuthenticator}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an mTLS authenticator
      effect: read
      questions:
      - Is a particular mTLS authenticator enabled?
      - Can I inspect one authenticator by its ID under an mTLS identity provider?
      instructions:
      - text: Get mTLS authenticator {mtlsAuthenticator} of provider {mtlsIdentityProvider} in realm {realm}.
        slots:
          mtlsAuthenticator: path.mtlsAuthenticator
          mtlsIdentityProvider: path.mtlsIdentityProvider
          realm: path.realm
      - text: Check whether authenticator {mtlsAuthenticator} on {mtlsIdentityProvider} in realm {realm} is enabled.
        slots:
          mtlsAuthenticator: path.mtlsAuthenticator
          mtlsIdentityProvider: path.mtlsIdentityProvider
          realm: path.realm
      method: generated
      generated: '2026-09-26'
- target: $.paths['/realms/{realm}/mtlsIdentityProviders/{mtlsIdentityProvider}/authenticators/{mtlsAuthenticator}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Enable or disable an mTLS authenticator
      effect: write
      questions:
      - How do I temporarily turn off certificate authentication for an mTLS provider?
      - Can I re-enable a disabled mTLS authenticator?
      instructions:
      - text: Set authenticator {mtlsAuthenticator} on {mtlsIdentityProvider} in realm {realm} to enabled={enabled}.
        slots:
          mtlsAuthenticator: path.mtlsAuthenticator
          mtlsIdentityProvider: path.mtlsIdentityProvider
          realm: path.realm
          enabled: requestBody.enabled
      - text: Disable mTLS authenticator {mtlsAuthenticator} for provider {mtlsIdentityProvider} in realm {realm}.
        slots:
          mtlsAuthenticator: path.mtlsAuthenticator
          mtlsIdentityProvider: path.mtlsIdentityProvider
          realm: path.realm
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apps/{app}/mtlsAuthenticators'].get
  update:
    x-apievangelist-phrasing:
      intent: List mTLS authenticators configured for an app
      effect: read
      questions:
      - Which mTLS authenticators is my app set up to use?
      - Can an app authenticate with client certificates, and through which authenticators?
      instructions:
      - text: List the mTLS authenticators configured for app {app}.
        slots:
          app: path.app
      - text: Show which certificate authenticators app {app} uses.
        slots:
          app: path.app
      method: generated
      generated: '2026-09-26'