Elastic Stack (ELK Stack) Trusted Environments API

openapi: 3.2.0
info:
  version: '1'
  title: Elastic Cloud Enterprise Trusted Environments API
  termsOfService: ''
servers:
- url: https://{{hostname}}/api/v1
security:
- basicAuth: []
- apiKey: []
tags:
- name: TrustedEnvironments
paths:
  /trusted-environments:
    get:
      tags:
      - TrustedEnvironments
      summary: Get trusted environments
      description: Returns the list of trusted environments for the organization. If no organization is passed in, the organization attached to the user is assumed.
      operationId: get-trusted-envs
      parameters:
      - name: organization_id
        in: query
        description: (Optional) Organization Id for which to retrieve the trusted environments
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Trusted environments for this organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ElasticsearchClusterTrustSettings'
        '404':
          description: 'Organization not found. (code: `organization.not_found`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - organization.not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
      x-doc:
        tag: TrustedEnvironments
components:
  schemas:
    BasicFailedReplyElement:
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: string
          description: A structured code representing the error type that occurred
        message:
          type: string
          description: A human readable message describing the error that occurred
        fields:
          type: array
          description: If the error can be tied to a specific field or fields in the user request, this lists those fields
          items:
            type: string
    TrustedCertificate:
      type: object
      required:
      - pem
      properties:
        pem:
          type: string
          description: The public ca certificate as string in PEM format.
        metadata:
          description: Metadata about the certificate, including fingerprint and expiry date. Generated by the Cloud service and ignored on write.
          readOnly: true
          $ref: '#/components/schemas/CertificateMetaData'
      description: An x509 certificate used by a DirectTrustRelationship
    AccountTrustRelationship:
      type: object
      required:
      - account_id
      - trust_all
      properties:
        account_id:
          type: string
          description: the ID of the Account
        name:
          type: string
          description: A human readable name of the trust relationship
        trust_all:
          type: boolean
          description: If true, all clusters in this account will by default be trusted and the `trust_allowlist` is ignored.
        trust_allowlist:
          type: array
          description: The list of clusters to trust. Only used when `trust_all` is false.
          items:
            type: string
      description: The trust relationship with the clusters of one account.
    BasicFailedReply:
      type: object
      required:
      - errors
      properties:
        errors:
          type: array
          description: A list of errors that occurred in the failing request
          items:
            $ref: '#/components/schemas/BasicFailedReplyElement'
    ExternalTrustRelationship:
      type: object
      required:
      - trust_all
      - trust_relationship_id
      properties:
        trust_relationship_id:
          type: string
          description: The ID of the external trust relationship
        name:
          type: string
          description: The name of the external trust relationship. Retrieved from the TrustRelationship and ignored on write.
        trust_all:
          type: boolean
          description: If true, all clusters in this external entity will be trusted and the `trust_allowlist` is ignored.
        trust_allowlist:
          type: array
          description: The list of clusters to trust. Only used when `trust_all` is false.
          items:
            type: string
      description: The trust relationship with external entities (remote environments, remote accounts...).
    DirectTrustRelationship:
      type: object
      required:
      - certificates
      - name
      - trust_all
      properties:
        uid:
          type: string
          description: Auto generated identifier for this trust, allows distinguishing between update vs remove and add.
        name:
          type: string
          description: a human readable name of the trust relationship
        type:
          type: string
          description: The type can either be ESS, ECE, generic or proxy. If none is specified, then generic is assumed. If proxy is specified, trust_all should be false and trust_allowlist, scope_id and additional_node_names should be omitted.
          enum:
          - ECE
          - ESS
          - generic
          - proxy
        trust_all:
          type: boolean
          description: If true, scope_id is required and the `trust_allowlist` is ignored and all clusters matching the scope id will be trusted.
        trust_allowlist:
          type: array
          description: The list of clusters with matching scope to trust. Only used when `trust_all` is false. Providing one or more clusters makes scope_id mandatory.
          items:
            type: string
        scope_id:
          type: string
          example: abc123
          description: A lowercase alphanumerical string of max 32 characters. Usually an organization id or an environment id, but could really be any suitable suffix for clusters using the CA certificate of this trust. Required unless trust_all is false and trust_allowlist is empty.
        additional_node_names:
          type: array
          description: A list of node names trusted in addition to those deducible from trust_allowlist and scope id. Allows trusting nodes that don't have a scoped name at the cost of maintaining the list. Mandatory if scope id is not defined. Wildcards are not allowed.
          items:
            type: string
        certificates:
          type: array
          description: The public ca certificate(s) to trust. Only one is required, but it is possible to specify multiple certificates in order to facilitate key rotation.
          items:
            $ref: '#/components/schemas/TrustedCertificate'
      description: The trust relationship with entities trusted directly having their certificate bundled together with the trust settings.
    CertificateMetaData:
      type: object
      required:
      - fingerprint
      - valid_from
      - valid_to
      properties:
        fingerprint:
          type: string
          description: The fingerprint of the certificate
        valid_to:
          type: string
          format: date-time
          description: The expiry date of the certificate in UTC
        valid_from:
          type: string
          format: date-time
          description: The valid from date of the certificate in UTC
        also_trusted_by:
          type: array
          description: Other deployments also trusting this certificate
          items:
            type: string
      description: The certificate MetaData
    ElasticsearchClusterTrustSettings:
      type: object
      properties:
        accounts:
          type: array
          description: The list of trust relationships with different accounts
          items:
            $ref: '#/components/schemas/AccountTrustRelationship'
        external:
          type: array
          description: The list of trust relationships with external entities
          items:
            $ref: '#/components/schemas/ExternalTrustRelationship'
        direct:
          type: array
          description: The list of trust relationships where the certificate is bundled with the trust setting. Allows configuring trust for clusters running outside of an Elastic Cloud managed environment or in an Elastic Cloud environment without an environment level trust established.
          items:
            $ref: '#/components/schemas/DirectTrustRelationship'
      description: Configuration of trust with other clusters.
  securitySchemes:
    apiKey:
      type: apiKey
      name: Authorization
      in: header
    basicAuth:
      type: http
      scheme: basic
x-elastic:
  curl:
    auth: '-H "Authorization: ApiKey $ECE_API_KEY"'