Elastic Stack (ELK Stack) Authentication API

openapi: 3.2.0
info:
  version: '1'
  title: Elastic Cloud Enterprise Authentication API
  termsOfService: ''
servers:
- url: https://{{hostname}}/api/v1
security:
- basicAuth: []
- apiKey: []
tags:
- name: Authentication
paths:
  /users/auth:
    get:
      tags:
      - Authentication
      summary: User authentication information
      description: Provides authentication information about a user, including elevated permission status and TOTP device availability.
      operationId: get-authentication-info
      responses:
        '200':
          description: User authentication information response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationInfo'
      x-doc:
        tag: Authentication
  /users/auth/_login:
    post:
      tags:
      - Authentication
      summary: Login to ECE
      description: Authenticates against available users.
      operationId: login
      responses:
        '200':
          description: Login successful, returns the token in the body (if 'login_state.path' not specified)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '302':
          description: Redirects to '/sso/token#BEARER_TOKEN?state=LOGIN_STATE' with the fragment containing a bearer token  (if 'login_state.path' is specified)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmptyResponse'
        '401':
          description: 'The supplied authentication is invalid. (code: `root.unauthenticated`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - root.unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
        '501':
          description: 'The administrator needs to configure the authentication cluster. (code: `authc.no_authentication_cluster`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - authc.no_authentication_cluster
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
        '502':
          description: 'The authentication cluster failed to process the request. The response body contains details about the error. (code: `authc.authentication_cluster_error`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - authc.authentication_cluster_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
      x-doc:
        tag: Authentication
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
        description: The login request
        required: true
  /users/auth/_logout:
    post:
      tags:
      - Authentication
      summary: Logout from ECE
      description: Destroys the current session.
      operationId: logout
      responses:
        '200':
          description: The current session was successfully destroyed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmptyResponse'
        '501':
          description: 'The administrator needs to configure the authentication cluster. (code: `authc.no_authentication_cluster`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - authc.no_authentication_cluster
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
        '502':
          description: 'The authentication cluster failed to process the request. The response body contains details about the error. (code: `authc.authentication_cluster_error`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - authc.authentication_cluster_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
      x-doc:
        tag: Authentication
  /users/auth/_refresh:
    post:
      tags:
      - Authentication
      summary: Refresh authentication token
      description: Issues a new authentication token.
      operationId: refresh-token
      responses:
        '200':
          description: The token refreshed successfully and was returned in the body of the response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '401':
          description: 'The authentication token is invalid or expired. (code: `root.unauthorized`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - root.unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
        '501':
          description: 'The administrator needs to configure the authentication cluster. (code: `authc.no_authentication_cluster`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - authc.no_authentication_cluster
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
        '502':
          description: 'The authentication cluster failed to process the request. The response body contains details about the error. (code: `authc.authentication_cluster_error`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - authc.authentication_cluster_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
      x-doc:
        tag: Authentication
  /users/auth/keys:
    get:
      tags:
      - Authentication
      summary: Get all API keys
      description: Retrieves the metadata for the API keys the caller is allowed to see.
      operationId: get-api-keys
      parameters:
      - name: next_page
        in: query
        description: Pagination cursor to get the next page of records
        required: false
        schema:
          type: string
      responses:
        '200':
          description: The metadata for the API keys is retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeysResponse'
      x-doc:
        tag: Authentication
    post:
      tags:
      - Authentication
      summary: Create API key
      description: Creates a new API key.
      operationId: create-api-key
      responses:
        '201':
          description: The API key is created and returned in the body of the response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyResponse'
        '400':
          description: 'The request is invalid. Specify a different request, then try again. (code: `api_keys.invalid_input`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - api_keys.invalid_input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
      x-doc:
        tag: Authentication
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateApiKeyRequest'
        description: The request to create the API key
        required: true
    delete:
      tags:
      - Authentication
      summary: Delete API keys
      description: Delete or invalidate API keys.
      operationId: delete-api-keys
      responses:
        '200':
          description: The API keys are deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmptyResponse'
      x-doc:
        tag: Authentication
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteApiKeysRequest'
        description: The request to delete API keys
        required: true
  /users/auth/keys/_all:
    get:
      tags:
      - Authentication
      summary: Get all API keys for all users
      description: 'DEPRECATED: Scheduled to be removed in a future release.


        Retrieves the metadata for all of the API keys for all users.'
      operationId: get-users-api-keys
      responses:
        '200':
          description: The metadata for the API keys is retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeysResponse'
      x-doc:
        tag: Authentication
    delete:
      tags:
      - Authentication
      summary: Delete API keys of multiple users
      description: Delete or invalidate the API keys for multiple users.
      operationId: delete-users-api-keys
      responses:
        '200':
          description: The API keys are deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmptyResponse'
      x-doc:
        tag: Authentication
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteUsersApiKeysRequest'
        description: The request to delete API keys.
        required: true
  /users/auth/keys/{api_key_id}:
    get:
      tags:
      - Authentication
      summary: Get API key
      description: Retrieves the metadata for an API key.
      operationId: get-api-key
      parameters:
      - name: api_key_id
        in: path
        description: The API Key ID.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The API key metadata is retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyResponse'
        '404':
          description: 'The {api_key_id} can''t be found. (code: `api_keys.key_not_found`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - api_keys.key_not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
      x-doc:
        tag: Authentication
    delete:
      tags:
      - Authentication
      summary: Delete API key
      description: Delete or invalidate the API key.
      operationId: delete-api-key
      parameters:
      - name: api_key_id
        in: path
        description: The API Key ID.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The API key is deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmptyResponse'
        '404':
          description: 'The {api_key_id} can''t be found. (code: `api_keys.key_not_found`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - api_keys.key_not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
      x-doc:
        tag: Authentication
  /users/auth/methods:
    get:
      tags:
      - Authentication
      summary: Available authentication methods
      description: Provides information about available authentication methods.
      operationId: methods
      responses:
        '200':
          description: Available authentication methods response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AvailableAuthenticationMethods'
      x-doc:
        tag: Authentication
  /users/auth/saml/_callback:
    post:
      tags:
      - Authentication
      summary: SAML callback
      description: Accepts a callback request from an identity provider and authenticates the user.
      operationId: saml-callback
      responses:
        '302':
          description: Redirects to the UI endpoint with an authorization token in the fragment and the relay state, if it was specified during the initialization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmptyResponse'
        '401':
          description: 'The supplied SAML response is invalid. (code: `root.unauthenticated`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - root.unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
        '501':
          description: 'The administrator needs to configure the authentication cluster. (code: `authc.no_authentication_cluster`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - authc.no_authentication_cluster
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
        '502':
          description: 'The authentication cluster failed to process the request. The response body contains details about the error. (code: `authc.authentication_cluster_error`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - authc.authentication_cluster_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
      x-doc:
        tag: Authentication
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                SAMLResponse:
                  type: string
                  description: A message issued by the identity provider to the service provider
                RelayState:
                  type: string
                  description: The optional relay state that the API (service provider) sent to the identity provider.
              required:
              - SAMLResponse
  /users/auth/saml/_init:
    get:
      tags:
      - Authentication
      summary: Initiate SAML protocol
      description: Calls the authentication cluster to initiate SAML Single Sign-on (Web Browser SSO profile) protocol and redirects the user to the identity provider for authentication. The authentication cluster must be configured prior to initiation.
      operationId: saml-init
      parameters:
      - name: state
        in: query
        description: An optional relay state that is sent back to the client after the user is authenticated
        required: false
        schema:
          type: string
      - name: realm
        in: query
        description: An optional SAML realm to use for authentication
        required: false
        schema:
          type: string
      responses:
        '302':
          description: Redirects the client to the identity provider with a SAML authentication request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmptyResponse'
        '501':
          description: 'The administrator needs to configure the authentication cluster. (code: `authc.no_authentication_cluster`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - authc.no_authentication_cluster
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
        '502':
          description: 'The authentication cluster failed to process the request. The response body contains details about the error. (code: `authc.authentication_cluster_error`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - authc.authentication_cluster_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
      x-doc:
        tag: Authentication
  /users/{user_id}/auth/keys:
    get:
      tags:
      - Authentication
      summary: Get API key metadata for all keys created by the user
      description: Retrieves metadata for all API keys created by the given user.
      operationId: get-user-api-keys
      parameters:
      - name: user_id
        in: path
        description: The user ID.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The API key metadata is retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeysResponse'
        '404':
          description: 'The {user_id} can''t be found. (code: `api_keys.user_not_found`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - api_keys.user_not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
      x-doc:
        tag: Authentication
    delete:
      tags:
      - Authentication
      summary: Delete API keys for a user
      description: Delete or invalidate all of the API keys for a user.
      operationId: delete-user-api-keys
      parameters:
      - name: user_id
        in: path
        description: The user ID.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The API key is deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmptyResponse'
        '404':
          description: 'The {user_id} can''t be found. (code: `api_keys.user_not_found`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - api_keys.user_not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
      x-doc:
        tag: Authentication
  /users/{user_id}/auth/keys/{api_key_id}:
    get:
      tags:
      - Authentication
      summary: Get a user API key
      description: Retrieves the API key metadata for a user.
      operationId: get-user-api-key
      parameters:
      - name: user_id
        in: path
        description: The user ID.
        required: true
        schema:
          type: string
      - name: api_key_id
        in: path
        description: The API Key ID.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The API key metadata is retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyResponse'
        '404':
          description: 'The {api_key_id} can''t be found. (code: `api_keys.key_not_found`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - api_keys.key_not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
      x-doc:
        tag: Authentication
    delete:
      tags:
      - Authentication
      summary: Delete an API key for a user
      description: Delete or invalidate an API key for a user.
      operationId: delete-user-api-key
      parameters:
      - name: user_id
        in: path
        description: The user ID.
        required: true
        schema:
          type: string
      - name: api_key_id
        in: path
        description: The API Key ID.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The API key is deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmptyResponse'
        '404':
          description: 'The {api_key_id} can''t be found. (code: `api_keys.key_not_found`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - api_keys.key_not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
      x-doc:
        tag: Authentication
components:
  schemas:
    ProjectRoleAssignment:
      type: object
      required:
      - organization_id
      - role_id
      properties:
        role_id:
          type: string
          description: The ID of the role that is assigned.
        organization_id:
          type: string
          description: The ID of the organization the role is scoped to.
        all:
          type: boolean
          description: When true, the role applies to all projects in the organization, otherwise the role is scoped to the projects specified in `project_ids`.
        project_ids:
          type: array
          description: The IDs of the projects the role is scoped to. Must be absent if `all` is true, and present if `all` is false.
          items:
            type: string
        application_roles:
          type: array
          description: If provided, the user assigned this role assignment will be granted this application role when signing in to the project(s) specified in the role assignment.
          items:
            type: string
      description: Assignment for a role with project scope.
    ApiKeysResponse:
      type: object
      required:
      - keys
      properties:
        keys:
          type: array
          description: The list of API keys.
          items:
            $ref: '#/components/schemas/ApiKeyResponse'
        next_page:
          type: string
          description: A cursor to get the next page of results
      description: The response model for the API keys.
    OrganizationRoleAssignment:
      type: object
      required:
      - organization_id
      - role_id
      properties:
        role_id:
          type: string
          description: The ID of the role that is assigned.
        organization_id:
          type: string
          description: The ID of the organization the role is scoped to.
        application_roles:
          type: array
          description: If provided, the user assigned this role assignment will be granted this application role when signing in to a deployment or project
          items:
            type: string
      description: Assignment for a role with organization scope.
    AvailableAuthenticationMethods:
      type: object
      required:
      - openid
      - password
      - saml
      - sso_methods
      properties:
        password:
          type: boolean
          description: Indicates that username and password authentication is available.
        saml:
          type: boolean
          description: Indicates that SAML single sign-on authentication is available.
        openid:
          type: boolean
          description: '> WARNING

            > This endpoint is deprecated and scheduled to be removed in the next major version. This field is no longer used and will always be false.


            '
        sso_methods:
          type: array
          description: Lists details for the available single sign-on methods.
          items:
            $ref: '#/components/schemas/SsoAuthenticationMethodInfo'
      description: 'Specifies the authentication methods that are enabled on the Elasticsearch cluster. NOTE: When all fields are `false`, only the Platform admin and Platform viewer are available.'
    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
    CreateApiKeyRequest:
      type: object
      required:
      - description
      properties:
        description:
          type: string
          description: API key description. Useful if there are multiple keys
        expiration:
          type: string
          description: 'The optional expiration for the API key, provided as a duration (ex: ''1d'', ''3h'')'
        role_assignments:
          description: The optional roles for the API key. Takes the role of the creator if not specified. Currently unavailable in self-hosted ECE.
          $ref: '#/components/schemas/RoleAssignments'
      description: The request payload that creates the API keys.
    AuthenticationInfo:
      type: object
      required:
      - has_elevated_permissions
      - refresh_token_url
      properties:
        has_totp_device:
          type: boolean
          description: 'Deprecated: True if the user has an available TOTP device'
        totp_device_source:
          type: string
          description: 'Deprecated: The TOTP device source'
        has_elevated_permissions:
          type: boolean
          description: 'Deprecated: True if the user has elevated permissions'
        elevated_permissions_expire_at:
          type: string
          format: date-time
          description: 'Deprecated: The UTC time when elevated permissions will expire, if the user has elevated permissions'
        totp_device_source_enable_mfa_href:
          type: string
          description: 'Deprecated: URL for configuring an MFA TOTP device.  Does not apply when totp_device_source is ''native''.'
        refresh_token_url:
          type: string
          description: The API to be used when refreshing the current user's JWT
        expires_at:
          type: string
          format: date-time
          description: The UTC time when current authentication will expire. Applies to only token based authentication
      description: A user's authentication info
    UserApiKey:
      type: object
      required:
      - api_key_id
      - user_id
      properties:
        user_id:
          type: string
          description: The user ID.
        api_key_id:
          type: string
          description: The API key ID.
      description: The model to specify a user and their API key in a delete request.
    EmptyResponse:
      type: object
    LoginRequest:
      type: object
      required:
      - password
      - username
      properties:
        username:
          type: string
          description: The username part of the login request
        password:
          type: string
          description: The plain text password part of the login request
        login_state:
          $ref: '#/components/schemas/LoginState'
      description: The body of a login request.
    LoginState:
      type: object
      properties:
        path:
          type: string
          description: The path to which to redirect post login - if not specified then no redirect is performed, instead 200 is returned with the token in the body
      description: Configure how the API responds after a successful login.
    PlatformRoleAssignment:
      type: object
      required:
      - role_id
      properties:
        role_id:
          type: string
          description: The ID of the role that is assigned.
      description: Assignment for a role with platform scope.
    DeploymentRoleAssignment:
      type: object
      required:
      - organization_id
      - role_id
      properties:
        role_id:
          type: string
          description: The ID of the role that is assigned.
        organization_id:
          type: string
          description: The ID of the organization the role is scoped to.
        all:
          type: boolean
          description: When true, the role applies to all deployments in the organization, otherwise the role is scoped to the deployments specified in `deployment_ids`.
        deployment_ids:
          type: array
          description: The IDs of the deployments the role is scoped to. Must be absent if `all` is true, and present if `all` is false.
          items:
            type: string
        application_roles:
          type: array
          description: If provided, the user assigned this role assignment will be granted this application role when signing in to the deployment(s) specified in the role assignment.
          items:
            type: string
      description: Assignment for a role with deployment scope.
    RoleAssignments:
      type: object
      properties:
        platform:
          type: array
          description: Assignments for roles with platform scope.
          items:
            $ref: '#/components/schemas/PlatformRoleAssignment'
        organization:
          type: array
          description: Assignments for roles with organization scope.
          items:
            $ref: '#/components/schemas/OrganizationRoleAssignment'
        deployment:
          type: array
          description: Assignments for roles with deployment scope.
          items:
            $ref: '#/components/schemas/DeploymentRoleAssignment'
        project:
          description: Assignments for roles with project scope.
          $ref: '#/components/schemas/ProjectRoleAssignments'
      description: Roles assigned to users, API keys or organization invitations. Currently unavailable in self-hosted ECE.
    ApiKeyResponse:
      type: object
      required:
      - creation_date
      - description
      - id
      properties:
        id:
          type: string
          description: The API key ID.
        user_id:
          type: string
          description: The user ID.
        organization_id:
          type: string
          description: The organization ID linked to the API key
        description:
          type: string
          description: 'The API key description. TIP: Useful whe

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