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 when you have multiple API keys.' key: type: string description: 'The API key. TIP: Since the API key is returned only once, save it in a safe place.' creation_date: type: string format: date-time description: The date/time for when the API key is created. expiration_date: type: string format: date-time description: The date/time when the API key expires. role_assignments: description: The optional roles for the API key. Currently unavailable in self-hosted ECE. $ref: '#/components/schemas/RoleAssignments' description: The response model for an API key. ProjectRoleAssignments: type: object properties: elasticsearch: type: array description: The Elasticsearch project-scoped role assignments to set items: $ref: '#/components/schemas/ProjectRoleAssignment' observability: type: array description: The Observability project-scoped role assignments to set items: $ref: '#/components/schemas/ProjectRoleAssignment' security: type: array description: The Security project-scoped role assignments to set items: $ref: '#/components/schemas/ProjectRoleAssignment' workplaceai: type: array description: The WorkplaceAI project-scoped role assignments to set items: $ref: '#/components/schemas/ProjectRoleAssignment' vectordb: type: array description: The VectorDB project-scoped role assignments to set items: $ref: '#/components/schemas/ProjectRoleAssignment' description: Assignments for roles with project scope. DeleteUsersApiKeysRequest: type: object required: - user_api_keys properties: user_api_keys: type: array description: The list of API key IDs. items: $ref: '#/components/schemas/UserApiKey' description: The request payload that deletes the API keys. 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' DeleteApiKeysRequest: type: object required: - keys properties: keys: type: array description: The list of API key IDs. items: type: string description: The request payload that deletes the API keys. TokenResponse: type: object required: - session_expiration_time - token properties: token: type: string description: The authorization bearer token that you use in subsequent requests session_expiration_time: type: string format: date-time description: The time that the session token will expire description: The response value after a login without redirect configured, or after elevated permissions are enabled or disabled. SsoAuthenticationMethodInfo: type: object required: - name - sso_type - url properties: sso_type: type: string description: Indicates the protocol of the single sign-on method. enum: - saml name: type: string description: The friendly name of the single sign-on method. url: type: string description: The URL to initiate the single sign-on login. 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.' securitySchemes: apiKey: type: apiKey name: Authorization in: header basicAuth: type: http scheme: basic x-elastic: curl: auth: '-H "Authorization: ApiKey $ECE_API_KEY"'