Elastic Stack (ELK Stack) Iam Service API

openapi: 3.2.0
info:
  version: '1'
  title: Elastic Cloud Enterprise Iam Service API
  termsOfService: ''
servers:
- url: https://{{hostname}}/api/v1
security:
- basicAuth: []
- apiKey: []
tags:
- name: IamService
paths:
  /organizations:
    get:
      tags:
      - IamService
      summary: List organizations
      description: Fetch organizations available to the current user. Currently unavailable in self-hosted ECE.
      operationId: list-organizations
      responses:
        '200':
          description: Organizations fetched successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationList'
        '401':
          description: 'User not found. (code: `user.not_found`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - user.not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
      x-doc:
        tag: Organizations
  /organizations/invitations/{invitation_token}:
    get:
      tags:
      - IamService
      summary: Get organization invitation
      description: Gets a single invitation to an organization by token. Currently unavailable in self-hosted ECE.
      operationId: get-organization-invitation
      parameters:
      - name: invitation_token
        in: path
        description: Organization invitation token
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Organization invitation fetched successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationInvitation'
        '404':
          description: 'Invitation not found. (code: `organization.invitation_not_found`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - organization.invitation_not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
      x-doc:
        tag: Organizations
  /organizations/{organization_id}:
    get:
      tags:
      - IamService
      summary: Fetch organization information
      description: Fetch a single organization by id. Currently unavailable in self-hosted ECE.
      operationId: get-organization
      parameters:
      - name: organization_id
        in: path
        description: Identifier for the Organization
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Organization fetched successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Organization'
        '401':
          description: 'User not found. (code: `user.not_found`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - user.not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
        '403':
          description: 'The current user does not have access to the requested organization. (code: `organization.invalid_access`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - organization.invalid_access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
        '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: Organizations
    put:
      tags:
      - IamService
      summary: Update organization
      description: '> WARNING

        > This endpoint is deprecated and scheduled to be removed in the next major version.


        Updates an existing organization. Currently unavailable in self-hosted ECE.'
      operationId: update-organization
      parameters:
      - name: organization_id
        in: path
        description: Identifier for the Organization
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Organization updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Organization'
        '400':
          description: '* Name must be between 2 and 30 characters. (code: `organization.invalid_name`)

            * User already has an organization. (code: `organization.user_organization_already_exists`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - organization.invalid_name
                - organization.user_organization_already_exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
        '401':
          description: You are not authorized to perform this action
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
        '403':
          description: 'The current user does not have access to the requested organization. (code: `organization.invalid_access`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - organization.invalid_access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
        '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: Organizations
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationRequest'
        description: The organization to update
        required: true
  /organizations/{organization_id}/domains:
    get:
      tags:
      - IamService
      summary: Get domain claims
      description: Get domain claims for the organization.
      operationId: domain-claim-get-domain-claims
      parameters:
      - name: organization_id
        in: path
        description: Identifier for the Organization
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The claimed domains for the organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetOrganizationClaimedDomainsResponse'
        '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: IamService
    delete:
      tags:
      - IamService
      summary: Delete domain claim
      description: Delete domain claim.
      operationId: domain-claim-delete
      parameters:
      - name: organization_id
        in: path
        description: Identifier for the Organization
        required: true
        schema:
          type: string
      responses:
        '200':
          description: With status 200 ok to signal the domain has been unclaimed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmptyResponse'
        '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'
        '400':
          description: 'An IdP is configured for the organization. (code: `org.idp.idp_configured`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - org.idp.idp_configured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
        '409':
          description: 'Concurrent organization modification. (code: `org.domain_claim.concurrent_organization_modification`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - org.domain_claim.concurrent_organization_modification
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
      x-doc:
        tag: IamService
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteDomainClaimRequest'
        description: The domain claim to remove
        required: true
  /organizations/{organization_id}/domains/_generate_verification_code:
    post:
      tags:
      - IamService
      summary: Generate verification code
      description: Generate verification code for the domain claim challenge.
      operationId: domain-claim-generate-verification-code
      parameters:
      - name: organization_id
        in: path
        description: Identifier for the Organization
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The verification code response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationCodeResponse'
        '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: IamService
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerificationCodeRequest'
        description: The verification code request
        required: true
  /organizations/{organization_id}/domains/_verify:
    post:
      tags:
      - IamService
      summary: Verify domain claim
      description: Verify domain claim challenge.
      operationId: domain-claim-verify-domain
      parameters:
      - name: organization_id
        in: path
        description: Identifier for the Organization
        required: true
        schema:
          type: string
      responses:
        '200':
          description: With status 200 ok to signal the domain has been claimed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmptyResponse'
        '449':
          description: The challenge can not be verified at the moment, please retry later
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmptyResponse'
        '400':
          description: 'Domain claim already exists. (code: `org.domain_claim.already_exists`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - org.domain_claim.already_exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
        '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'
        '409':
          description: 'Concurrent organization modification. (code: `org.domain_claim.concurrent_organization_modification`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - org.domain_claim.concurrent_organization_modification
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
      x-doc:
        tag: IamService
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DomainVerificationRequest'
        description: The verification code request
        required: true
  /organizations/{organization_id}/idp:
    get:
      tags:
      - IamService
      summary: Get organization IdP
      description: Gets the oranization's IdP. Currently unavailable in self-hosted ECE.
      operationId: get-organization-idp
      parameters:
      - name: organization_id
        in: path
        description: Identifier for the Organization
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The IdP info
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationIdp'
        '404':
          description: 'IdP was not configured yet. (code: `org.idp.idp_not_configured`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - org.idp.idp_not_configured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
      x-doc:
        tag: Organizations
    put:
      tags:
      - IamService
      summary: Setup organization IdP
      description: Sets up an organization's IdP. Currently unavailable in self-hosted ECE.
      operationId: setup-organization-idp
      parameters:
      - name: organization_id
        in: path
        description: Identifier for the Organization
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The IdP info
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationIdp'
        '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: Organizations
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdpConfigurationRequest'
        description: The IdP configuration
        required: true
    delete:
      tags:
      - IamService
      summary: Tear down organization IdP
      description: Tear down up an organization's IdP. Currently unavailable in self-hosted ECE.
      operationId: teardown-organization-idp
      parameters:
      - name: organization_id
        in: path
        description: Identifier for the Organization
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The IdP was successfully removed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmptyResponse'
        '404':
          description: 'Organization IdP not configured. (code: `org.idp.idp_not_configured`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - org.idp.idp_not_configured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
      x-doc:
        tag: Organizations
  /organizations/{organization_id}/idp/metadata.xml:
    get:
      tags:
      - IamService
      summary: Get organization service provider SAML2 metadata.xml for configuring the identity provider
      description: Gets the oranization's IdP metadata.xml. Currently unavailable in self-hosted ECE.
      operationId: get-organization-idp-metadata
      parameters:
      - name: organization_id
        in: path
        description: Identifier for the Organization
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The IdP info
          content:
            application/xml:
              schema:
                type: string
        '404':
          description: 'IdP was not configured yet. (code: `org.idp.idp_not_configured`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - org.idp.idp_not_configured
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
      x-doc:
        tag: Organizations
  /organizations/{organization_id}/invitations:
    get:
      tags:
      - IamService
      summary: List organization invitations
      description: Fetch open invitations to the selected organization. Currently unavailable in self-hosted ECE.
      operationId: list-organization-invitations
      parameters:
      - name: organization_id
        in: path
        description: Identifier for the Organization
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Organization invitations fetched successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationInvitations'
        '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: Organizations
    post:
      tags:
      - IamService
      summary: Create organization invitations
      description: Creates or refreshes organization invitations. Currently unavailable in self-hosted ECE.
      operationId: create-organization-invitations
      parameters:
      - name: organization_id
        in: path
        description: Identifier for the Organization
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Organization invitations created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationInvitations'
        '400':
          description: '* Invitation email was not valid. (code: `organization.invitation_invalid_email`)

            * Invitation already sent. (code: `organization.invitation_already_exists`)

            * User already belongs to organization. (code: `organization.user_organization_already_belongs`)

            * Request exceeds maximum pending invitations per organization. (code: `organization.invitations_pending_limit_exceeded`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - organization.invitation_invalid_email
                - organization.invitation_already_exists
                - organization.user_organization_already_belongs
                - organization.invitations_pending_limit_exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
        '403':
          description: 'The current user authentication is not valid. (code: `root.invalid_authentication`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - root.invalid_authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
        '404':
          description: '* Organization not found. (code: `organization.not_found`)

            * User not found. (code: `user.not_found`)

            * Invitation sender does not belong to organization. (code: `organization.user_organization_does_not_belong`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - organization.not_found
                - user.not_found
                - organization.user_organization_does_not_belong
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
        '429':
          description: 'Request exceeds organization invitation creation rate limits. (code: `organization.invitations_rate_limit_exceeded`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - organization.invitations_rate_limit_exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
      x-doc:
        tag: Organizations
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationInvitationRequest'
        description: The organization invitations to create or refresh
        required: true
  /organizations/{organization_id}/invitations/{invitation_tokens}:
    delete:
      tags:
      - IamService
      summary: Delete organization invitations
      description: Deletes one or more organization invitations. Currently unavailable in self-hosted ECE.
      operationId: delete-organization-invitations
      parameters:
      - name: organization_id
        in: path
        description: Identifier for the Organization
        required: true
        schema:
          type: string
      - name: invitation_tokens
        in: path
        description: CSV list of Invitation tokens
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Organization invitations deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmptyResponse'
        '400':
          description: 'No valid invitation token was supplied. (code: `root.invalid_data`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - root.invalid_data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
        '404':
          description: '* Organization not found. (code: `organization.not_found`)

            * Invitation not found. (code: `organization.invitation_not_found`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - organization.not_found
                - organization.invitation_not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
      x-doc:
        tag: Organizations
  /organizations/{organization_id}/members:
    get:
      tags:
      - IamService
      summary: List organization members
      description: Fetch users belonging to the selected organization. Currently unavailable in self-hosted ECE.
      operationId: list-organization-members
      parameters:
      - name: organization_id
        in: path
        description: Identifier for the Organization
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Organization members fetched successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationMemberships'
        '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: Organizations
  /organizations/{organization_id}/members/{user_ids}:
    delete:
      tags:
      - IamService
      summary: Delete organization memberships
      description: Deletes one or more organization memberships. Currently unavailable in self-hosted ECE.
      operationId: delete-organization-memberships
      parameters:
      - name: organization_id
        in: path
        description: Identifier for the Organization
        required: true
        schema:
          type: string
      - name: user_ids
        in: path
        description: CSV list of User identifiers
        required: true
        schema:
          type: string
      - name: force
        in: query
        description: Whether or not to force the removal of Org memberships (effective only for Platform Admins)
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Organization membership deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmptyResponse'
        '404':
          description: '* User not found. (code: `user.not_found`)

            * Organization not found. (code: `organization.not_found`)

            * Organization membership not found. (code: `organization.membership_not_found`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - user.not_found
                - organization.not_found
                - organization.membership_not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
      x-doc:
        tag: Organizations
  /organizations/{organization_id}/role_mappings:
    get:
      tags:
      - IamService
      summary: Get role mappings
      description: Gets the organization role  mappings. Currently unavailable in self-hosted ECE.
      operationId: get-role-mappings
      parameters:
      - name: organization_id
        in: path
        description: Identifier for the Organization
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The IdP info
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetRoleMappingsResponse'
        '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: Organizations
    post:
      tags:
      - IamService
      summary: Adds role mapping
      description: Adds the role assignments applicable when logging via SSO. Currently unavailable in self-hosted ECE.
      operationId: add-role-mappings-individually
      parameters:
      - name: organization_id
        in: path
        description: Identifier for the Organization
        required: true
        schema:
          type: string
      responses:
        '201':
          description: An empty response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmptyResponse'
        '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'
        '400':
          description: '* Invalid rule. (code: `org.role_mapping_rule.ambiguous_rule`)

            * Empty rule. (code: `org.role_mapping_rule.empty_rule`)

            * Validation error. (code: `org.role_mapping_rule.syntax_error`)

            * Validation error. (code: `org.role_mapping_rule.email_syntax_error`)

            * Validation error. (code: `org.role_mapping_rule.too_many_role_mappings`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - org.role

# --- truncated at 32 KB (108 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/elk-stack/refs/heads/main/openapi/elk-stack-iamservice-api-openapi.yml