Security

class elasticsearch.client.SecurityClient(client)
Parameters:

client (BaseClient)

activate_user_profile(*, grant_type=None, access_token=None, error_trace=None, filter_path=None, human=None, password=None, pretty=None, username=None, body=None)

Activate a user profile. Create or update a user profile on behalf of another user. NOTE: The user profile feature is designed only for use by Kibana and Elastic’s Observability, Enterprise Search, and Elastic Security solutions. Individual users and external applications should not call this API directly. The calling application must have either an access_token or a combination of username and password for the user that the profile document is intended for. Elastic reserves the right to change or remove this feature in future releases without prior notice. This API creates or updates a profile document for end users with information that is extracted from the user’s authentication object including username, full_name, roles, and the authentication realm. For example, in the JWT access_token case, the profile user’s username is extracted from the JWT token claim pointed to by the claims.principal setting of the JWT realm that authenticated the token. When updating a profile document, the API enables the document if it was disabled. Any updates do not change existing content for either the labels or data fields.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-activate-user-profile.html

Parameters:

  • grant_type (str | Literal['access_token', 'password'] | None) – The type of grant.

  • access_token (str | None) – The user’s Elasticsearch access token or JWT. Both access and id JWT token types are supported and they depend on the underlying JWT realm configuration. If you specify the access_token grant type, this parameter is required. It is not valid with other grant types.

  • password (str | None) – The user’s password. If you specify the password grant type, this parameter is required. It is not valid with other grant types.

  • username (str | None) – The username that identifies the user. If you specify the password grant type, this parameter is required. It is not valid with other grant types.

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

  • body (Dict[str, Any] | None)

Return type:

ObjectApiResponse[Any]

authenticate(*, error_trace=None, filter_path=None, human=None, pretty=None)

Authenticate a user. Authenticates a user and returns information about the authenticated user. Include the user information in a [basic auth header](https://en.wikipedia.org/wiki/Basic_access_authentication). A successful call returns a JSON structure that shows user information such as their username, the roles that are assigned to the user, any assigned metadata, and information about the realms that authenticated and authorized the user. If the user cannot be authenticated, this API returns a 401 status code.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-authenticate.html

Parameters:
Return type:

ObjectApiResponse[Any]

bulk_delete_role(*, names=None, error_trace=None, filter_path=None, human=None, pretty=None, refresh=None, body=None)

Bulk delete roles. The role management APIs are generally the preferred way to manage roles, rather than using file-based role management. The bulk delete roles API cannot delete roles that are defined in roles files.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-bulk-delete-role.html

Parameters:

  • names (Sequence[str] | None) – An array of role names to delete

  • refresh (bool | str | Literal['false', 'true', 'wait_for'] | None) – If true (the default) then refresh the affected shards to make this operation visible to search, if wait_for then wait for a refresh to make this operation visible to search, if false then do nothing with refreshes.

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

  • body (Dict[str, Any] | None)

Return type:

ObjectApiResponse[Any]

bulk_put_role(*, roles=None, error_trace=None, filter_path=None, human=None, pretty=None, refresh=None, body=None)

Bulk create or update roles. The role management APIs are generally the preferred way to manage roles, rather than using file-based role management. The bulk create or update roles API cannot update roles that are defined in roles files.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-bulk-put-role.html

Parameters:

  • roles (Mapping[str, Mapping[str, Any]] | None) – A dictionary of role name to RoleDescriptor objects to add or update

  • refresh (bool | str | Literal['false', 'true', 'wait_for'] | None) – If true (the default) then refresh the affected shards to make this operation visible to search, if wait_for then wait for a refresh to make this operation visible to search, if false then do nothing with refreshes.

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

  • body (Dict[str, Any] | None)

Return type:

ObjectApiResponse[Any]

bulk_update_api_keys(*, ids=None, error_trace=None, expiration=None, filter_path=None, human=None, metadata=None, pretty=None, role_descriptors=None, body=None)

Bulk update API keys. Update the attributes for multiple API keys. IMPORTANT: It is not possible to use an API key as the authentication credential for this API. To update API keys, the owner user’s credentials are required. This API is similar to the update API key API but enables you to apply the same update to multiple API keys in one API call. This operation can greatly improve performance over making individual updates. It is not possible to update expired or invalidated API keys. This API supports updates to API key access scope, metadata and expiration. The access scope of each API key is derived from the role_descriptors you specify in the request and a snapshot of the owner user’s permissions at the time of the request. The snapshot of the owner’s permissions is updated automatically on every call. IMPORTANT: If you don’t specify role_descriptors in the request, a call to this API might still change an API key’s access scope. This change can occur if the owner user’s permissions have changed since the API key was created or last modified. A successful request returns a JSON structure that contains the IDs of all updated API keys, the IDs of API keys that already had the requested changes and did not require an update, and error details for any failed update.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-bulk-update-api-keys.html

Parameters:

  • ids (str | Sequence[str] | None) – The API key identifiers.

  • expiration (str | Literal[-1] | ~typing.Literal[0] | None) – Expiration time for the API keys. By default, API keys never expire. This property can be omitted to leave the value unchanged.

  • metadata (Mapping[str, Any] | None) – Arbitrary nested metadata to associate with the API keys. Within the metadata object, top-level keys beginning with an underscore (_) are reserved for system usage. Any information specified with this parameter fully replaces metadata previously associated with the API key.

  • role_descriptors (Mapping[str, Mapping[str, Any]] | None) – The role descriptors to assign to the API keys. An API key’s effective permissions are an intersection of its assigned privileges and the point-in-time snapshot of permissions of the owner user. You can assign new privileges by specifying them in this parameter. To remove assigned privileges, supply the role_descriptors parameter as an empty object {}. If an API key has no assigned privileges, it inherits the owner user’s full permissions. The snapshot of the owner’s permissions is always updated, whether you supply the role_descriptors parameter. The structure of a role descriptor is the same as the request for the create API keys API.

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

  • body (Dict[str, Any] | None)

Return type:

ObjectApiResponse[Any]

change_password(*, username=None, error_trace=None, filter_path=None, human=None, password=None, password_hash=None, pretty=None, refresh=None, body=None)

Change passwords. Change the passwords of users in the native realm and built-in users.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-change-password.html

Parameters:

  • username (str | None) – The user whose password you want to change. If you do not specify this parameter, the password is changed for the current user.

  • password (str | None) – The new password value. Passwords must be at least 6 characters long.

  • password_hash (str | None) – A hash of the new password value. This must be produced using the same hashing algorithm as has been configured for password storage. For more details, see the explanation of the xpack.security.authc.password_hashing.algorithm setting.

  • refresh (bool | str | Literal['false', 'true', 'wait_for'] | None) – If true (the default) then refresh the affected shards to make this operation visible to search, if wait_for then wait for a refresh to make this operation visible to search, if false then do nothing with refreshes.

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

  • body (Dict[str, Any] | None)

Return type:

ObjectApiResponse[Any]

clear_api_key_cache(*, ids, error_trace=None, filter_path=None, human=None, pretty=None)

Clear the API key cache. Evict a subset of all entries from the API key cache. The cache is also automatically cleared on state changes of the security index.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-clear-api-key-cache.html

Parameters:

  • ids (str | Sequence[str]) – Comma-separated list of API key IDs to evict from the API key cache. To evict all API keys, use *. Does not support other wildcard patterns.

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

Return type:

ObjectApiResponse[Any]

clear_cached_privileges(*, application, error_trace=None, filter_path=None, human=None, pretty=None)

Clear the privileges cache. Evict privileges from the native application privilege cache. The cache is also automatically cleared for applications that have their privileges updated.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-clear-privilege-cache.html

Parameters:

  • application (str) – A comma-separated list of application names

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

Return type:

ObjectApiResponse[Any]

clear_cached_realms(*, realms, error_trace=None, filter_path=None, human=None, pretty=None, usernames=None)

Clear the user cache. Evict users from the user cache. You can completely clear the cache or evict specific users.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-clear-cache.html

Parameters:

  • realms (str | Sequence[str]) – Comma-separated list of realms to clear

  • usernames (Sequence[str] | None) – Comma-separated list of usernames to clear from the cache

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

Return type:

ObjectApiResponse[Any]

clear_cached_roles(*, name, error_trace=None, filter_path=None, human=None, pretty=None)

Clear the roles cache. Evict roles from the native role cache.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-clear-role-cache.html

Parameters:
Return type:

ObjectApiResponse[Any]

clear_cached_service_tokens(*, namespace, service, name, error_trace=None, filter_path=None, human=None, pretty=None)

Clear service account token caches. Evict a subset of all entries from the service account token caches.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-clear-service-token-caches.html

Parameters:

  • namespace (str) – An identifier for the namespace

  • service (str) – An identifier for the service name

  • name (str | Sequence[str]) – A comma-separated list of service token names

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

Return type:

ObjectApiResponse[Any]

create_api_key(*, error_trace=None, expiration=None, filter_path=None, human=None, metadata=None, name=None, pretty=None, refresh=None, role_descriptors=None, body=None)

Create an API key. Create an API key for access without requiring basic authentication. A successful request returns a JSON structure that contains the API key, its unique id, and its name. If applicable, it also returns expiration information for the API key in milliseconds. NOTE: By default, API keys never expire. You can specify expiration information when you create the API keys.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-create-api-key.html

Parameters:

  • expiration (str | Literal[-1] | ~typing.Literal[0] | None) – Expiration time for the API key. By default, API keys never expire.

  • metadata (Mapping[str, Any] | None) – Arbitrary metadata that you want to associate with the API key. It supports nested data structure. Within the metadata object, keys beginning with _ are reserved for system usage.

  • name (str | None) – Specifies the name for this API key.

  • refresh (bool | str | Literal['false', 'true', 'wait_for'] | None) – If true (the default) then refresh the affected shards to make this operation visible to search, if wait_for then wait for a refresh to make this operation visible to search, if false then do nothing with refreshes.

  • role_descriptors (Mapping[str, Mapping[str, Any]] | None) – An array of role descriptors for this API key. This parameter is optional. When it is not specified or is an empty array, then the API key will have a point in time snapshot of permissions of the authenticated user. If you supply role descriptors then the resultant permissions would be an intersection of API keys permissions and authenticated user’s permissions thereby limiting the access scope for API keys. The structure of role descriptor is the same as the request for create role API. For more details, see create or update roles API.

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

  • body (Dict[str, Any] | None)

Return type:

ObjectApiResponse[Any]

create_cross_cluster_api_key(*, access=None, name=None, error_trace=None, expiration=None, filter_path=None, human=None, metadata=None, pretty=None, body=None)

Create a cross-cluster API key. Create an API key of the cross_cluster type for the API key based remote cluster access. A cross_cluster API key cannot be used to authenticate through the REST interface. IMPORTANT: To authenticate this request you must use a credential that is not an API key. Even if you use an API key that has the required privilege, the API returns an error. Cross-cluster API keys are created by the Elasticsearch API key service, which is automatically enabled. NOTE: Unlike REST API keys, a cross-cluster API key does not capture permissions of the authenticated user. The API key’s effective permission is exactly as specified with the access property. A successful request returns a JSON structure that contains the API key, its unique ID, and its name. If applicable, it also returns expiration information for the API key in milliseconds. By default, API keys never expire. You can specify expiration information when you create the API keys. Cross-cluster API keys can only be updated with the update cross-cluster API key API. Attempting to update them with the update REST API key API or the bulk update REST API keys API will result in an error.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-create-cross-cluster-api-key.html

Parameters:

  • access (Mapping[str, Any] | None) – The access to be granted to this API key. The access is composed of permissions for cross-cluster search and cross-cluster replication. At least one of them must be specified. NOTE: No explicit privileges should be specified for either search or replication access. The creation process automatically converts the access specification to a role descriptor which has relevant privileges assigned accordingly.

  • name (str | None) – Specifies the name for this API key.

  • expiration (str | Literal[-1] | ~typing.Literal[0] | None) – Expiration time for the API key. By default, API keys never expire.

  • metadata (Mapping[str, Any] | None) – Arbitrary metadata that you want to associate with the API key. It supports nested data structure. Within the metadata object, keys beginning with _ are reserved for system usage.

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

  • body (Dict[str, Any] | None)

Return type:

ObjectApiResponse[Any]

create_service_token(*, namespace, service, name=None, error_trace=None, filter_path=None, human=None, pretty=None, refresh=None)

Create a service account token. Create a service accounts token for access without requiring basic authentication.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-create-service-token.html

Parameters:

  • namespace (str) – An identifier for the namespace

  • service (str) – An identifier for the service name

  • name (str | None) – An identifier for the token name

  • refresh (bool | str | Literal['false', 'true', 'wait_for'] | None) – If true then refresh the affected shards to make this operation visible to search, if wait_for (the default) then wait for a refresh to make this operation visible to search, if false then do nothing with refreshes.

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

Return type:

ObjectApiResponse[Any]

delegate_pki(*, x509_certificate_chain=None, error_trace=None, filter_path=None, human=None, pretty=None, body=None)

Delegate PKI authentication. This API implements the exchange of an X509Certificate chain for an Elasticsearch access token. The certificate chain is validated, according to RFC 5280, by sequentially considering the trust configuration of every installed PKI realm that has delegation.enabled set to true. A successfully trusted client certificate is also subject to the validation of the subject distinguished name according to thw username_pattern of the respective realm. This API is called by smart and trusted proxies, such as Kibana, which terminate the user’s TLS session but still want to authenticate the user by using a PKI realm—-​as if the user connected directly to Elasticsearch. IMPORTANT: The association between the subject public key in the target certificate and the corresponding private key is not validated. This is part of the TLS authentication process and it is delegated to the proxy that calls this API. The proxy is trusted to have performed the TLS authentication and this API translates that authentication into an Elasticsearch access token.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-delegate-pki-authentication.html

Parameters:

  • x509_certificate_chain (Sequence[str] | None) – The X509Certificate chain, which is represented as an ordered string array. Each string in the array is a base64-encoded (Section 4 of RFC4648 - not base64url-encoded) of the certificate’s DER encoding. The first element is the target certificate that contains the subject distinguished name that is requesting access. This may be followed by additional certificates; each subsequent certificate is used to certify the previous one.

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

  • body (Dict[str, Any] | None)

Return type:

ObjectApiResponse[Any]

delete_privileges(*, application, name, error_trace=None, filter_path=None, human=None, pretty=None, refresh=None)

Delete application privileges.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-delete-privilege.html

Parameters:

  • application (str) – Application name

  • name (str | Sequence[str]) – Privilege name

  • refresh (bool | str | Literal['false', 'true', 'wait_for'] | None) – If true (the default) then refresh the affected shards to make this operation visible to search, if wait_for then wait for a refresh to make this operation visible to search, if false then do nothing with refreshes.

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

Return type:

ObjectApiResponse[Any]

delete_role(*, name, error_trace=None, filter_path=None, human=None, pretty=None, refresh=None)

Delete roles. Delete roles in the native realm.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-delete-role.html

Parameters:

  • name (str) – Role name

  • refresh (bool | str | Literal['false', 'true', 'wait_for'] | None) – If true (the default) then refresh the affected shards to make this operation visible to search, if wait_for then wait for a refresh to make this operation visible to search, if false then do nothing with refreshes.

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

Return type:

ObjectApiResponse[Any]

delete_role_mapping(*, name, error_trace=None, filter_path=None, human=None, pretty=None, refresh=None)

Delete role mappings.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-delete-role-mapping.html

Parameters:

  • name (str) – Role-mapping name

  • refresh (bool | str | Literal['false', 'true', 'wait_for'] | None) – If true (the default) then refresh the affected shards to make this operation visible to search, if wait_for then wait for a refresh to make this operation visible to search, if false then do nothing with refreshes.

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

Return type:

ObjectApiResponse[Any]

delete_service_token(*, namespace, service, name, error_trace=None, filter_path=None, human=None, pretty=None, refresh=None)

Delete service account tokens. Delete service account tokens for a service in a specified namespace.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-delete-service-token.html

Parameters:

  • namespace (str) – An identifier for the namespace

  • service (str) – An identifier for the service name

  • name (str) – An identifier for the token name

  • refresh (bool | str | Literal['false', 'true', 'wait_for'] | None) – If true then refresh the affected shards to make this operation visible to search, if wait_for (the default) then wait for a refresh to make this operation visible to search, if false then do nothing with refreshes.

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

Return type:

ObjectApiResponse[Any]

delete_user(*, username, error_trace=None, filter_path=None, human=None, pretty=None, refresh=None)

Delete users. Delete users from the native realm.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-delete-user.html

Parameters:

  • username (str) – username

  • refresh (bool | str | Literal['false', 'true', 'wait_for'] | None) – If true (the default) then refresh the affected shards to make this operation visible to search, if wait_for then wait for a refresh to make this operation visible to search, if false then do nothing with refreshes.

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

Return type:

ObjectApiResponse[Any]

disable_user(*, username, error_trace=None, filter_path=None, human=None, pretty=None, refresh=None)

Disable users. Disable users in the native realm.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-disable-user.html

Parameters:

  • username (str) – The username of the user to disable

  • refresh (bool | str | Literal['false', 'true', 'wait_for'] | None) – If true (the default) then refresh the affected shards to make this operation visible to search, if wait_for then wait for a refresh to make this operation visible to search, if false then do nothing with refreshes.

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

Return type:

ObjectApiResponse[Any]

disable_user_profile(*, uid, error_trace=None, filter_path=None, human=None, pretty=None, refresh=None)

Disable a user profile. Disable user profiles so that they are not visible in user profile searches. NOTE: The user profile feature is designed only for use by Kibana and Elastic’s Observability, Enterprise Search, and Elastic Security solutions. Individual users and external applications should not call this API directly. Elastic reserves the right to change or remove this feature in future releases without prior notice. When you activate a user profile, its automatically enabled and visible in user profile searches. You can use the disable user profile API to disable a user profile so it’s not visible in these searches. To re-enable a disabled user profile, use the enable user profile API .

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-disable-user-profile.html

Parameters:

  • uid (str) – Unique identifier for the user profile.

  • refresh (bool | str | Literal['false', 'true', 'wait_for'] | None) – If ‘true’, Elasticsearch refreshes the affected shards to make this operation visible to search. If ‘wait_for’, it waits for a refresh to make this operation visible to search. If ‘false’, it does nothing with refreshes.

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

Return type:

ObjectApiResponse[Any]

enable_user(*, username, error_trace=None, filter_path=None, human=None, pretty=None, refresh=None)

Enable users. Enable users in the native realm.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-enable-user.html

Parameters:

  • username (str) – The username of the user to enable

  • refresh (bool | str | Literal['false', 'true', 'wait_for'] | None) – If true (the default) then refresh the affected shards to make this operation visible to search, if wait_for then wait for a refresh to make this operation visible to search, if false then do nothing with refreshes.

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

Return type:

ObjectApiResponse[Any]

enable_user_profile(*, uid, error_trace=None, filter_path=None, human=None, pretty=None, refresh=None)

Enable a user profile. Enable user profiles to make them visible in user profile searches. NOTE: The user profile feature is designed only for use by Kibana and Elastic’s Observability, Enterprise Search, and Elastic Security solutions. Individual users and external applications should not call this API directly. Elastic reserves the right to change or remove this feature in future releases without prior notice. When you activate a user profile, it’s automatically enabled and visible in user profile searches. If you later disable the user profile, you can use the enable user profile API to make the profile visible in these searches again.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-enable-user-profile.html

Parameters:

  • uid (str) – A unique identifier for the user profile.

  • refresh (bool | str | Literal['false', 'true', 'wait_for'] | None) – If ‘true’, Elasticsearch refreshes the affected shards to make this operation visible to search. If ‘wait_for’, it waits for a refresh to make this operation visible to search. If ‘false’, nothing is done with refreshes.

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

Return type:

ObjectApiResponse[Any]

enroll_kibana(*, error_trace=None, filter_path=None, human=None, pretty=None)

Enroll Kibana. Enable a Kibana instance to configure itself for communication with a secured Elasticsearch cluster.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-kibana-enrollment.html

Parameters:
Return type:

ObjectApiResponse[Any]

enroll_node(*, error_trace=None, filter_path=None, human=None, pretty=None)

Enroll a node. Enroll a new node to allow it to join an existing cluster with security features enabled.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-node-enrollment.html

Parameters:
Return type:

ObjectApiResponse[Any]

get_api_key(*, active_only=None, error_trace=None, filter_path=None, human=None, id=None, name=None, owner=None, pretty=None, realm_name=None, username=None, with_limited_by=None, with_profile_uid=None)

Get API key information. Retrieves information for one or more API keys. NOTE: If you have only the manage_own_api_key privilege, this API returns only the API keys that you own. If you have read_security, manage_api_key or greater privileges (including manage_security), this API returns all API keys regardless of ownership.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-get-api-key.html

Parameters:

  • active_only (bool | None) – A boolean flag that can be used to query API keys that are currently active. An API key is considered active if it is neither invalidated, nor expired at query time. You can specify this together with other parameters such as owner or name. If active_only is false, the response will include both active and inactive (expired or invalidated) keys.

  • id (str | None) – An API key id. This parameter cannot be used with any of name, realm_name or username.

  • name (str | None) – An API key name. This parameter cannot be used with any of id, realm_name or username. It supports prefix search with wildcard.

  • owner (bool | None) – A boolean flag that can be used to query API keys owned by the currently authenticated user. The realm_name or username parameters cannot be specified when this parameter is set to true as they are assumed to be the currently authenticated ones.

  • realm_name (str | None) – The name of an authentication realm. This parameter cannot be used with either id or name or when owner flag is set to true.

  • username (str | None) – The username of a user. This parameter cannot be used with either id or name or when owner flag is set to true.

  • with_limited_by (bool | None) – Return the snapshot of the owner user’s role descriptors associated with the API key. An API key’s actual permission is the intersection of its assigned role descriptors and the owner user’s role descriptors.

  • with_profile_uid (bool | None) – Determines whether to also retrieve the profile uid, for the API key owner principal, if it exists.

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

Return type:

ObjectApiResponse[Any]

get_builtin_privileges(*, error_trace=None, filter_path=None, human=None, pretty=None)

Get builtin privileges. Get the list of cluster privileges and index privileges that are available in this version of Elasticsearch.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-get-builtin-privileges.html

Parameters:
Return type:

ObjectApiResponse[Any]

get_privileges(*, application=None, name=None, error_trace=None, filter_path=None, human=None, pretty=None)

Get application privileges.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-get-privileges.html

Parameters:
Return type:

ObjectApiResponse[Any]

get_role(*, name=None, error_trace=None, filter_path=None, human=None, pretty=None)

Get roles. Get roles in the native realm. The role management APIs are generally the preferred way to manage roles, rather than using file-based role management. The get roles API cannot retrieve roles that are defined in roles files.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-get-role.html

Parameters:

  • name (str | Sequence[str] | None) – The name of the role. You can specify multiple roles as a comma-separated list. If you do not specify this parameter, the API returns information about all roles.

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

Return type:

ObjectApiResponse[Any]

get_role_mapping(*, name=None, error_trace=None, filter_path=None, human=None, pretty=None)

Get role mappings. Role mappings define which roles are assigned to each user. The role mapping APIs are generally the preferred way to manage role mappings rather than using role mapping files. The get role mappings API cannot retrieve role mappings that are defined in role mapping files.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-get-role-mapping.html

Parameters:

  • name (str | Sequence[str] | None) – The distinct name that identifies the role mapping. The name is used solely as an identifier to facilitate interaction via the API; it does not affect the behavior of the mapping in any way. You can specify multiple mapping names as a comma-separated list. If you do not specify this parameter, the API returns information about all role mappings.

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

Return type:

ObjectApiResponse[Any]

get_service_accounts(*, namespace=None, service=None, error_trace=None, filter_path=None, human=None, pretty=None)

Get service accounts. Get a list of service accounts that match the provided path parameters.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-get-service-accounts.html

Parameters:

  • namespace (str | None) – Name of the namespace. Omit this parameter to retrieve information about all service accounts. If you omit this parameter, you must also omit the service parameter.

  • service (str | None) – Name of the service name. Omit this parameter to retrieve information about all service accounts that belong to the specified namespace.

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

Return type:

ObjectApiResponse[Any]

get_service_credentials(*, namespace, service, error_trace=None, filter_path=None, human=None, pretty=None)

Get service account credentials.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-get-service-credentials.html

Parameters:

  • namespace (str) – Name of the namespace.

  • service (str) – Name of the service name.

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

Return type:

ObjectApiResponse[Any]

get_settings(*, error_trace=None, filter_path=None, human=None, master_timeout=None, pretty=None)

Get security index settings. Get the user-configurable settings for the security internal index (.security and associated indices).

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-get-settings.html

Parameters:

  • master_timeout (str | Literal[-1] | ~typing.Literal[0] | None) – Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

Return type:

ObjectApiResponse[Any]

get_token(*, error_trace=None, filter_path=None, grant_type=None, human=None, kerberos_ticket=None, password=None, pretty=None, refresh_token=None, scope=None, username=None, body=None)

Get a token. Create a bearer token for access without requiring basic authentication.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-get-token.html

Parameters:

  • grant_type (str | Literal['_kerberos', 'client_credentials', 'password', 'refresh_token'] | None)

  • kerberos_ticket (str | None)

  • password (str | None)

  • refresh_token (str | None)

  • scope (str | None)

  • username (str | None)

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

  • body (Dict[str, Any] | None)

Return type:

ObjectApiResponse[Any]

get_user(*, username=None, error_trace=None, filter_path=None, human=None, pretty=None, with_profile_uid=None)

Get users. Get information about users in the native realm and built-in users.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-get-user.html

Parameters:

  • username (str | Sequence[str] | None) – An identifier for the user. You can specify multiple usernames as a comma-separated list. If you omit this parameter, the API retrieves information about all users.

  • with_profile_uid (bool | None) – If true will return the User Profile ID for a user, if any.

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

Return type:

ObjectApiResponse[Any]

get_user_privileges(*, application=None, error_trace=None, filter_path=None, human=None, pretty=None, priviledge=None, username=None)

Get user privileges.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-get-user-privileges.html

Parameters:

  • application (str | None) – The name of the application. Application privileges are always associated with exactly one application. If you do not specify this parameter, the API returns information about all privileges for all applications.

  • priviledge (str | None) – The name of the privilege. If you do not specify this parameter, the API returns information about all privileges for the requested application.

  • username (None | str)

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

Return type:

ObjectApiResponse[Any]

get_user_profile(*, uid, data=None, error_trace=None, filter_path=None, human=None, pretty=None)

Get a user profile. Get a user’s profile using the unique profile ID. NOTE: The user profile feature is designed only for use by Kibana and Elastic’s Observability, Enterprise Search, and Elastic Security solutions. Individual users and external applications should not call this API directly. Elastic reserves the right to change or remove this feature in future releases without prior notice.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-get-user-profile.html

Parameters:

  • uid (str | Sequence[str]) – A unique identifier for the user profile.

  • data (str | Sequence[str] | None) – A comma-separated list of filters for the data field of the profile document. To return all content use data=*. To return a subset of content use data=<key> to retrieve content nested under the specified <key>. By default returns no data content.

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

Return type:

ObjectApiResponse[Any]

grant_api_key(*, api_key=None, grant_type=None, access_token=None, error_trace=None, filter_path=None, human=None, password=None, pretty=None, run_as=None, username=None, body=None)

Grant an API key. Create an API key on behalf of another user. This API is similar to the create API keys API, however it creates the API key for a user that is different than the user that runs the API. The caller must have authentication credentials (either an access token, or a username and password) for the user on whose behalf the API key will be created. It is not possible to use this API to create an API key without that user’s credentials. The user, for whom the authentication credentials is provided, can optionally “run as” (impersonate) another user. In this case, the API key will be created on behalf of the impersonated user. This API is intended be used by applications that need to create and manage API keys for end users, but cannot guarantee that those users have permission to create API keys on their own behalf. A successful grant API key API call returns a JSON structure that contains the API key, its unique id, and its name. If applicable, it also returns expiration information for the API key in milliseconds. By default, API keys never expire. You can specify expiration information when you create the API keys.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-grant-api-key.html

Parameters:

  • api_key (Mapping[str, Any] | None) – Defines the API key.

  • grant_type (str | Literal['access_token', 'password'] | None) – The type of grant. Supported grant types are: access_token, password.

  • access_token (str | None) – The user’s access token. If you specify the access_token grant type, this parameter is required. It is not valid with other grant types.

  • password (str | None) – The user’s password. If you specify the password grant type, this parameter is required. It is not valid with other grant types.

  • run_as (str | None) – The name of the user to be impersonated.

  • username (str | None) – The user name that identifies the user. If you specify the password grant type, this parameter is required. It is not valid with other grant types.

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

  • body (Dict[str, Any] | None)

Return type:

ObjectApiResponse[Any]

has_privileges(*, user=None, application=None, cluster=None, error_trace=None, filter_path=None, human=None, index=None, pretty=None, body=None)

Check user privileges. Determine whether the specified user has a specified list of privileges.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-has-privileges.html

Parameters:

  • user (str | None) – Username

  • application (Sequence[Mapping[str, Any]] | None)

  • cluster (Sequence[str | Literal['all', 'cancel_task', 'create_snapshot', 'cross_cluster_replication', 'cross_cluster_search', 'delegate_pki', 'grant_api_key', 'manage', 'manage_api_key', 'manage_autoscaling', 'manage_behavioral_analytics', 'manage_ccr', 'manage_data_frame_transforms', 'manage_data_stream_global_retention', 'manage_enrich', 'manage_ilm', 'manage_index_templates', 'manage_inference', 'manage_ingest_pipelines', 'manage_logstash_pipelines', 'manage_ml', 'manage_oidc', 'manage_own_api_key', 'manage_pipeline', 'manage_rollup', 'manage_saml', 'manage_search_application', 'manage_search_query_rules', 'manage_search_synonyms', 'manage_security', 'manage_service_account', 'manage_slm', 'manage_token', 'manage_transform', 'manage_user_profile', 'manage_watcher', 'monitor', 'monitor_data_frame_transforms', 'monitor_data_stream_global_retention', 'monitor_enrich', 'monitor_inference', 'monitor_ml', 'monitor_rollup', 'monitor_snapshot', 'monitor_stats', 'monitor_text_structure', 'monitor_transform', 'monitor_watcher', 'none', 'post_behavioral_analytics_event', 'read_ccr', 'read_fleet_secrets', 'read_ilm', 'read_pipeline', 'read_security', 'read_slm', 'transport_client', 'write_connector_secrets', 'write_fleet_secrets']] | None) – A list of the cluster privileges that you want to check.

  • index (Sequence[Mapping[str, Any]] | None)

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

  • body (Dict[str, Any] | None)

Return type:

ObjectApiResponse[Any]

has_privileges_user_profile(*, privileges=None, uids=None, error_trace=None, filter_path=None, human=None, pretty=None, body=None)

Check user profile privileges. Determine whether the users associated with the specified user profile IDs have all the requested privileges. NOTE: The user profile feature is designed only for use by Kibana and Elastic’s Observability, Enterprise Search, and Elastic Security solutions. Individual users and external applications should not call this API directly. Elastic reserves the right to change or remove this feature in future releases without prior notice.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-has-privileges-user-profile.html

Parameters:

  • privileges (Mapping[str, Any] | None) – An object containing all the privileges to be checked.

  • uids (Sequence[str] | None) – A list of profile IDs. The privileges are checked for associated users of the profiles.

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

  • body (Dict[str, Any] | None)

Return type:

ObjectApiResponse[Any]

invalidate_api_key(*, error_trace=None, filter_path=None, human=None, id=None, ids=None, name=None, owner=None, pretty=None, realm_name=None, username=None, body=None)

Invalidate API keys. This API invalidates API keys created by the create API key or grant API key APIs. Invalidated API keys fail authentication, but they can still be viewed using the get API key information and query API key information APIs, for at least the configured retention period, until they are automatically deleted. The manage_api_key privilege allows deleting any API keys. The manage_own_api_key only allows deleting API keys that are owned by the user. In addition, with the manage_own_api_key privilege, an invalidation request must be issued in one of the three formats: - Set the parameter owner=true. - Or, set both username and realm_name to match the user’s identity. - Or, if the request is issued by an API key, that is to say an API key invalidates itself, specify its ID in the ids field.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-invalidate-api-key.html

Parameters:

  • id (str | None)

  • ids (Sequence[str] | None) – A list of API key ids. This parameter cannot be used with any of name, realm_name, or username.

  • name (str | None) – An API key name. This parameter cannot be used with any of ids, realm_name or username.

  • owner (bool | None) – Can be used to query API keys owned by the currently authenticated user. The realm_name or username parameters cannot be specified when this parameter is set to true as they are assumed to be the currently authenticated ones.

  • realm_name (str | None) – The name of an authentication realm. This parameter cannot be used with either ids or name, or when owner flag is set to true.

  • username (str | None) – The username of a user. This parameter cannot be used with either ids or name, or when owner flag is set to true.

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

  • body (Dict[str, Any] | None)

Return type:

ObjectApiResponse[Any]

invalidate_token(*, error_trace=None, filter_path=None, human=None, pretty=None, realm_name=None, refresh_token=None, token=None, username=None, body=None)

Invalidate a token. The access tokens returned by the get token API have a finite period of time for which they are valid. After that time period, they can no longer be used. The time period is defined by the xpack.security.authc.token.timeout setting. The refresh tokens returned by the get token API are only valid for 24 hours. They can also be used exactly once. If you want to invalidate one or more access or refresh tokens immediately, use this invalidate token API.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-invalidate-token.html

Parameters:
Return type:

ObjectApiResponse[Any]

oidc_authenticate(*, nonce=None, redirect_uri=None, state=None, error_trace=None, filter_path=None, human=None, pretty=None, realm=None, body=None)

Authenticate OpenID Connect. Exchange an OpenID Connect authentication response message for an Elasticsearch internal access token and refresh token that can be subsequently used for authentication. Elasticsearch exposes all the necessary OpenID Connect related functionality with the OpenID Connect APIs. These APIs are used internally by Kibana in order to provide OpenID Connect based authentication, but can also be used by other, custom web applications or other clients.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-oidc-authenticate.html

Parameters:

  • nonce (str | None) – Associate a client session with an ID token and mitigate replay attacks. This value needs to be the same as the one that was provided to the /_security/oidc/prepare API or the one that was generated by Elasticsearch and included in the response to that call.

  • redirect_uri (str | None) – The URL to which the OpenID Connect Provider redirected the User Agent in response to an authentication request after a successful authentication. This URL must be provided as-is (URL encoded), taken from the body of the response or as the value of a location header in the response from the OpenID Connect Provider.

  • state (str | None) – Maintain state between the authentication request and the response. This value needs to be the same as the one that was provided to the /_security/oidc/prepare API or the one that was generated by Elasticsearch and included in the response to that call.

  • realm (str | None) – The name of the OpenID Connect realm. This property is useful in cases where multiple realms are defined.

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

  • body (Dict[str, Any] | None)

Return type:

ObjectApiResponse[Any]

oidc_logout(*, access_token=None, error_trace=None, filter_path=None, human=None, pretty=None, refresh_token=None, body=None)

Logout of OpenID Connect. Invalidate an access token and a refresh token that were generated as a response to the /_security/oidc/authenticate API. If the OpenID Connect authentication realm in Elasticsearch is accordingly configured, the response to this call will contain a URI pointing to the end session endpoint of the OpenID Connect Provider in order to perform single logout. Elasticsearch exposes all the necessary OpenID Connect related functionality with the OpenID Connect APIs. These APIs are used internally by Kibana in order to provide OpenID Connect based authentication, but can also be used by other, custom web applications or other clients.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-oidc-logout.html

Parameters:

  • access_token (str | None) – The access token to be invalidated.

  • refresh_token (str | None) – The refresh token to be invalidated.

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

  • body (Dict[str, Any] | None)

Return type:

ObjectApiResponse[Any]

oidc_prepare_authentication(*, error_trace=None, filter_path=None, human=None, iss=None, login_hint=None, nonce=None, pretty=None, realm=None, state=None, body=None)

Prepare OpenID connect authentication. Create an oAuth 2.0 authentication request as a URL string based on the configuration of the OpenID Connect authentication realm in Elasticsearch. The response of this API is a URL pointing to the Authorization Endpoint of the configured OpenID Connect Provider, which can be used to redirect the browser of the user in order to continue the authentication process. Elasticsearch exposes all the necessary OpenID Connect related functionality with the OpenID Connect APIs. These APIs are used internally by Kibana in order to provide OpenID Connect based authentication, but can also be used by other, custom web applications or other clients.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-oidc-prepare-authentication.html

Parameters:

  • iss (str | None) – In the case of a third party initiated single sign on, this is the issuer identifier for the OP that the RP is to send the authentication request to. It cannot be specified when realm is specified. One of realm or iss is required.

  • login_hint (str | None) – In the case of a third party initiated single sign on, it is a string value that is included in the authentication request as the login_hint parameter. This parameter is not valid when realm is specified.

  • nonce (str | None) – The value used to associate a client session with an ID token and to mitigate replay attacks. If the caller of the API does not provide a value, Elasticsearch will generate one with sufficient entropy and return it in the response.

  • realm (str | None) – The name of the OpenID Connect realm in Elasticsearch the configuration of which should be used in order to generate the authentication request. It cannot be specified when iss is specified. One of realm or iss is required.

  • state (str | None) – The value used to maintain state between the authentication request and the response, typically used as a Cross-Site Request Forgery mitigation. If the caller of the API does not provide a value, Elasticsearch will generate one with sufficient entropy and return it in the response.

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

  • body (Dict[str, Any] | None)

Return type:

ObjectApiResponse[Any]

put_privileges(*, privileges=None, body=None, error_trace=None, filter_path=None, human=None, pretty=None, refresh=None)

Create or update application privileges.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-put-privileges.html

Parameters:
Return type:

ObjectApiResponse[Any]

put_role(*, name, applications=None, cluster=None, description=None, error_trace=None, filter_path=None, global_=None, human=None, indices=None, metadata=None, pretty=None, refresh=None, remote_cluster=None, remote_indices=None, run_as=None, transient_metadata=None, body=None)

Create or update roles. The role management APIs are generally the preferred way to manage roles in the native realm, rather than using file-based role management. The create or update roles API cannot update roles that are defined in roles files. File-based role management is not available in Elastic Serverless.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-put-role.html

Parameters:

  • name (str) – The name of the role.

  • applications (Sequence[Mapping[str, Any]] | None) – A list of application privilege entries.

  • cluster (Sequence[str | Literal['all', 'cancel_task', 'create_snapshot', 'cross_cluster_replication', 'cross_cluster_search', 'delegate_pki', 'grant_api_key', 'manage', 'manage_api_key', 'manage_autoscaling', 'manage_behavioral_analytics', 'manage_ccr', 'manage_data_frame_transforms', 'manage_data_stream_global_retention', 'manage_enrich', 'manage_ilm', 'manage_index_templates', 'manage_inference', 'manage_ingest_pipelines', 'manage_logstash_pipelines', 'manage_ml', 'manage_oidc', 'manage_own_api_key', 'manage_pipeline', 'manage_rollup', 'manage_saml', 'manage_search_application', 'manage_search_query_rules', 'manage_search_synonyms', 'manage_security', 'manage_service_account', 'manage_slm', 'manage_token', 'manage_transform', 'manage_user_profile', 'manage_watcher', 'monitor', 'monitor_data_frame_transforms', 'monitor_data_stream_global_retention', 'monitor_enrich', 'monitor_inference', 'monitor_ml', 'monitor_rollup', 'monitor_snapshot', 'monitor_stats', 'monitor_text_structure', 'monitor_transform', 'monitor_watcher', 'none', 'post_behavioral_analytics_event', 'read_ccr', 'read_fleet_secrets', 'read_ilm', 'read_pipeline', 'read_security', 'read_slm', 'transport_client', 'write_connector_secrets', 'write_fleet_secrets']] | None) – A list of cluster privileges. These privileges define the cluster-level actions for users with this role.

  • description (str | None) – Optional description of the role descriptor

  • global – An object defining global privileges. A global privilege is a form of cluster privilege that is request-aware. Support for global privileges is currently limited to the management of application privileges.

  • indices (Sequence[Mapping[str, Any]] | None) – A list of indices permissions entries.

  • metadata (Mapping[str, Any] | None) – Optional metadata. Within the metadata object, keys that begin with an underscore (_) are reserved for system use.

  • refresh (bool | str | Literal['false', 'true', 'wait_for'] | None) – If true (the default) then refresh the affected shards to make this operation visible to search, if wait_for then wait for a refresh to make this operation visible to search, if false then do nothing with refreshes.

  • remote_cluster (Sequence[Mapping[str, Any]] | None) – A list of remote cluster permissions entries.

  • remote_indices (Sequence[Mapping[str, Any]] | None) – A list of remote indices permissions entries.

  • run_as (Sequence[str] | None) – A list of users that the owners of this role can impersonate. Note: in Serverless, the run-as feature is disabled. For API compatibility, you can still specify an empty run_as field, but a non-empty list will be rejected.

  • transient_metadata (Mapping[str, Any] | None) – Indicates roles that might be incompatible with the current cluster license, specifically roles with document and field level security. When the cluster license doesn’t allow certain features for a given role, this parameter is updated dynamically to list the incompatible features. If enabled is false, the role is ignored, but is still listed in the response from the authenticate API.

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • global_ (Mapping[str, Any] | None)

  • human (bool | None)

  • pretty (bool | None)

  • body (Dict[str, Any] | None)

Return type:

ObjectApiResponse[Any]

put_role_mapping(*, name, enabled=None, error_trace=None, filter_path=None, human=None, metadata=None, pretty=None, refresh=None, role_templates=None, roles=None, rules=None, run_as=None, body=None)

Create or update role mappings. Role mappings define which roles are assigned to each user. Each mapping has rules that identify users and a list of roles that are granted to those users. The role mapping APIs are generally the preferred way to manage role mappings rather than using role mapping files. The create or update role mappings API cannot update role mappings that are defined in role mapping files. This API does not create roles. Rather, it maps users to existing roles. Roles can be created by using the create or update roles API or roles files.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-put-role-mapping.html

Parameters:

  • name (str) – Role-mapping name

  • enabled (bool | None)

  • metadata (Mapping[str, Any] | None)

  • refresh (bool | str | Literal['false', 'true', 'wait_for'] | None) – If true (the default) then refresh the affected shards to make this operation visible to search, if wait_for then wait for a refresh to make this operation visible to search, if false then do nothing with refreshes.

  • role_templates (Sequence[Mapping[str, Any]] | None)

  • roles (Sequence[str] | None)

  • rules (Mapping[str, Any] | None)

  • run_as (Sequence[str] | None)

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

  • body (Dict[str, Any] | None)

Return type:

ObjectApiResponse[Any]

put_user(*, username, email=None, enabled=None, error_trace=None, filter_path=None, full_name=None, human=None, metadata=None, password=None, password_hash=None, pretty=None, refresh=None, roles=None, body=None)

Create or update users. A password is required for adding a new user but is optional when updating an existing user. To change a user’s password without updating any other fields, use the change password API.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-put-user.html

Parameters:

  • username (str) – The username of the User

  • email (None | str)

  • enabled (bool | None)

  • full_name (None | str)

  • metadata (Mapping[str, Any] | None)

  • password (str | None)

  • password_hash (str | None)

  • refresh (bool | str | Literal['false', 'true', 'wait_for'] | None) – If true (the default) then refresh the affected shards to make this operation visible to search, if wait_for then wait for a refresh to make this operation visible to search, if false then do nothing with refreshes.

  • roles (Sequence[str] | None)

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

  • body (Dict[str, Any] | None)

Return type:

ObjectApiResponse[Any]

query_api_keys(*, aggregations=None, aggs=None, error_trace=None, filter_path=None, from_=None, human=None, pretty=None, query=None, search_after=None, size=None, sort=None, typed_keys=None, with_limited_by=None, with_profile_uid=None, body=None)

Find API keys with a query. Get a paginated list of API keys and their information. You can optionally filter the results with a query.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-query-api-key.html

Parameters:

  • aggregations (Mapping[str, Mapping[str, Any]] | None) – Any aggregations to run over the corpus of returned API keys. Aggregations and queries work together. Aggregations are computed only on the API keys that match the query. This supports only a subset of aggregation types, namely: terms, range, date_range, missing, cardinality, value_count, composite, filter, and filters. Additionally, aggregations only run over the same subset of fields that query works with.

  • aggs (Mapping[str, Mapping[str, Any]] | None) – Any aggregations to run over the corpus of returned API keys. Aggregations and queries work together. Aggregations are computed only on the API keys that match the query. This supports only a subset of aggregation types, namely: terms, range, date_range, missing, cardinality, value_count, composite, filter, and filters. Additionally, aggregations only run over the same subset of fields that query works with.

  • from – Starting document offset. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after parameter.

  • query (Mapping[str, Any] | None) – A query to filter which API keys to return. If the query parameter is missing, it is equivalent to a match_all query. The query supports a subset of query types, including match_all, bool, term, terms, match, ids, prefix, wildcard, exists, range, and simple_query_string. You can query the following public information associated with an API key: id, type, name, creation, expiration, invalidated, invalidation, username, realm, and metadata.

  • search_after (Sequence[None | bool | float | int | str | Any] | None) – Search after definition

  • size (int | None) – The number of hits to return. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after parameter.

  • sort (Sequence[str | Mapping[str, Any]] | str | Mapping[str, Any] | None) – Other than id, all public fields of an API key are eligible for sorting. In addition, sort can also be applied to the _doc field to sort by index order.

  • typed_keys (bool | None) – Determines whether aggregation names are prefixed by their respective types in the response.

  • with_limited_by (bool | None) – Return the snapshot of the owner user’s role descriptors associated with the API key. An API key’s actual permission is the intersection of its assigned role descriptors and the owner user’s role descriptors.

  • with_profile_uid (bool | None) – Determines whether to also retrieve the profile uid, for the API key owner principal, if it exists.

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • from_ (int | None)

  • human (bool | None)

  • pretty (bool | None)

  • body (Dict[str, Any] | None)

Return type:

ObjectApiResponse[Any]

query_role(*, error_trace=None, filter_path=None, from_=None, human=None, pretty=None, query=None, search_after=None, size=None, sort=None, body=None)

Find roles with a query. Get roles in a paginated manner. You can optionally filter the results with a query.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-query-role.html

Parameters:

  • from – Starting document offset. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after parameter.

  • query (Mapping[str, Any] | None) – A query to filter which roles to return. If the query parameter is missing, it is equivalent to a match_all query. The query supports a subset of query types, including match_all, bool, term, terms, match, ids, prefix, wildcard, exists, range, and simple_query_string. You can query the following information associated with roles: name, description, metadata, applications.application, applications.privileges, applications.resources.

  • search_after (Sequence[None | bool | float | int | str | Any] | None) – Search after definition

  • size (int | None) – The number of hits to return. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after parameter.

  • sort (Sequence[str | Mapping[str, Any]] | str | Mapping[str, Any] | None) – All public fields of a role are eligible for sorting. In addition, sort can also be applied to the _doc field to sort by index order.

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • from_ (int | None)

  • human (bool | None)

  • pretty (bool | None)

  • body (Dict[str, Any] | None)

Return type:

ObjectApiResponse[Any]

query_user(*, error_trace=None, filter_path=None, from_=None, human=None, pretty=None, query=None, search_after=None, size=None, sort=None, with_profile_uid=None, body=None)

Find users with a query. Get information for users in a paginated manner. You can optionally filter the results with a query.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-query-user.html

Parameters:

  • from – Starting document offset. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after parameter.

  • query (Mapping[str, Any] | None) – A query to filter which users to return. If the query parameter is missing, it is equivalent to a match_all query. The query supports a subset of query types, including match_all, bool, term, terms, match, ids, prefix, wildcard, exists, range, and simple_query_string. You can query the following information associated with user: username, roles, enabled

  • search_after (Sequence[None | bool | float | int | str | Any] | None) – Search after definition

  • size (int | None) – The number of hits to return. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after parameter.

  • sort (Sequence[str | Mapping[str, Any]] | str | Mapping[str, Any] | None) – Fields eligible for sorting are: username, roles, enabled In addition, sort can also be applied to the _doc field to sort by index order.

  • with_profile_uid (bool | None) – If true will return the User Profile ID for the users in the query result, if any.

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • from_ (int | None)

  • human (bool | None)

  • pretty (bool | None)

  • body (Dict[str, Any] | None)

Return type:

ObjectApiResponse[Any]

saml_authenticate(*, content=None, ids=None, error_trace=None, filter_path=None, human=None, pretty=None, realm=None, body=None)

Authenticate SAML. Submit a SAML response message to Elasticsearch for consumption. NOTE: This API is intended for use by custom web applications other than Kibana. If you are using Kibana, refer to the documentation for configuring SAML single-sign-on on the Elastic Stack. The SAML message that is submitted can be: * A response to a SAML authentication request that was previously created using the SAML prepare authentication API. * An unsolicited SAML message in the case of an IdP-initiated single sign-on (SSO) flow. In either case, the SAML message needs to be a base64 encoded XML document with a root element of <Response>. After successful validation, Elasticsearch responds with an Elasticsearch internal access token and refresh token that can be subsequently used for authentication. This API endpoint essentially exchanges SAML responses that indicate successful authentication in the IdP for Elasticsearch access and refresh tokens, which can be used for authentication against Elasticsearch.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-saml-authenticate.html

Parameters:

  • content (str | None) – The SAML response as it was sent by the user’s browser, usually a Base64 encoded XML document.

  • ids (str | Sequence[str] | None) – A JSON array with all the valid SAML Request Ids that the caller of the API has for the current user.

  • realm (str | None) – The name of the realm that should authenticate the SAML response. Useful in cases where many SAML realms are defined.

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

  • body (Dict[str, Any] | None)

Return type:

ObjectApiResponse[Any]

saml_complete_logout(*, ids=None, realm=None, content=None, error_trace=None, filter_path=None, human=None, pretty=None, query_string=None, body=None)

Logout of SAML completely. Verifies the logout response sent from the SAML IdP. NOTE: This API is intended for use by custom web applications other than Kibana. If you are using Kibana, refer to the documentation for configuring SAML single-sign-on on the Elastic Stack. The SAML IdP may send a logout response back to the SP after handling the SP-initiated SAML Single Logout. This API verifies the response by ensuring the content is relevant and validating its signature. An empty response is returned if the verification process is successful. The response can be sent by the IdP with either the HTTP-Redirect or the HTTP-Post binding. The caller of this API must prepare the request accordingly so that this API can handle either of them.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-saml-complete-logout.html

Parameters:

  • ids (str | Sequence[str] | None) – A JSON array with all the valid SAML Request Ids that the caller of the API has for the current user.

  • realm (str | None) – The name of the SAML realm in Elasticsearch for which the configuration is used to verify the logout response.

  • content (str | None) – If the SAML IdP sends the logout response with the HTTP-Post binding, this field must be set to the value of the SAMLResponse form parameter from the logout response.

  • query_string (str | None) – If the SAML IdP sends the logout response with the HTTP-Redirect binding, this field must be set to the query string of the redirect URI.

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

  • body (Dict[str, Any] | None)

Return type:

ObjectApiResponse[Any]

saml_invalidate(*, query_string=None, acs=None, error_trace=None, filter_path=None, human=None, pretty=None, realm=None, body=None)

Invalidate SAML. Submit a SAML LogoutRequest message to Elasticsearch for consumption. NOTE: This API is intended for use by custom web applications other than Kibana. If you are using Kibana, refer to the documentation for configuring SAML single-sign-on on the Elastic Stack. The logout request comes from the SAML IdP during an IdP initiated Single Logout. The custom web application can use this API to have Elasticsearch process the LogoutRequest. After successful validation of the request, Elasticsearch invalidates the access token and refresh token that corresponds to that specific SAML principal and provides a URL that contains a SAML LogoutResponse message. Thus the user can be redirected back to their IdP.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-saml-invalidate.html

Parameters:

  • query_string (str | None) – The query part of the URL that the user was redirected to by the SAML IdP to initiate the Single Logout. This query should include a single parameter named SAMLRequest that contains a SAML logout request that is deflated and Base64 encoded. If the SAML IdP has signed the logout request, the URL should include two extra parameters named SigAlg and Signature that contain the algorithm used for the signature and the signature value itself. In order for Elasticsearch to be able to verify the IdP’s signature, the value of the query_string field must be an exact match to the string provided by the browser. The client application must not attempt to parse or process the string in any way.

  • acs (str | None) – The Assertion Consumer Service URL that matches the one of the SAML realm in Elasticsearch that should be used. You must specify either this parameter or the realm parameter.

  • realm (str | None) – The name of the SAML realm in Elasticsearch the configuration. You must specify either this parameter or the acs parameter.

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

  • body (Dict[str, Any] | None)

Return type:

ObjectApiResponse[Any]

saml_logout(*, token=None, error_trace=None, filter_path=None, human=None, pretty=None, refresh_token=None, body=None)

Logout of SAML. Submits a request to invalidate an access token and refresh token. NOTE: This API is intended for use by custom web applications other than Kibana. If you are using Kibana, refer to the documentation for configuring SAML single-sign-on on the Elastic Stack. This API invalidates the tokens that were generated for a user by the SAML authenticate API. If the SAML realm in Elasticsearch is configured accordingly and the SAML IdP supports this, the Elasticsearch response contains a URL to redirect the user to the IdP that contains a SAML logout request (starting an SP-initiated SAML Single Logout).

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-saml-logout.html

Parameters:

  • token (str | None) – The access token that was returned as a response to calling the SAML authenticate API. Alternatively, the most recent token that was received after refreshing the original one by using a refresh_token.

  • refresh_token (str | None) – The refresh token that was returned as a response to calling the SAML authenticate API. Alternatively, the most recent refresh token that was received after refreshing the original access token.

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

  • body (Dict[str, Any] | None)

Return type:

ObjectApiResponse[Any]

saml_prepare_authentication(*, acs=None, error_trace=None, filter_path=None, human=None, pretty=None, realm=None, relay_state=None, body=None)

Prepare SAML authentication. Create a SAML authentication request (<AuthnRequest>) as a URL string based on the configuration of the respective SAML realm in Elasticsearch. NOTE: This API is intended for use by custom web applications other than Kibana. If you are using Kibana, refer to the documentation for configuring SAML single-sign-on on the Elastic Stack. This API returns a URL pointing to the SAML Identity Provider. You can use the URL to redirect the browser of the user in order to continue the authentication process. The URL includes a single parameter named SAMLRequest, which contains a SAML Authentication request that is deflated and Base64 encoded. If the configuration dictates that SAML authentication requests should be signed, the URL has two extra parameters named SigAlg and Signature. These parameters contain the algorithm used for the signature and the signature value itself. It also returns a random string that uniquely identifies this SAML Authentication request. The caller of this API needs to store this identifier as it needs to be used in a following step of the authentication process.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-saml-prepare-authentication.html

Parameters:

  • acs (str | None) – The Assertion Consumer Service URL that matches the one of the SAML realms in Elasticsearch. The realm is used to generate the authentication request. You must specify either this parameter or the realm parameter.

  • realm (str | None) – The name of the SAML realm in Elasticsearch for which the configuration is used to generate the authentication request. You must specify either this parameter or the acs parameter.

  • relay_state (str | None) – A string that will be included in the redirect URL that this API returns as the RelayState query parameter. If the Authentication Request is signed, this value is used as part of the signature computation.

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

  • body (Dict[str, Any] | None)

Return type:

ObjectApiResponse[Any]

saml_service_provider_metadata(*, realm_name, error_trace=None, filter_path=None, human=None, pretty=None)

Create SAML service provider metadata. Generate SAML metadata for a SAML 2.0 Service Provider. The SAML 2.0 specification provides a mechanism for Service Providers to describe their capabilities and configuration using a metadata file. This API generates Service Provider metadata based on the configuration of a SAML realm in Elasticsearch.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-saml-sp-metadata.html

Parameters:

  • realm_name (str) – The name of the SAML realm in Elasticsearch.

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

Return type:

ObjectApiResponse[Any]

suggest_user_profiles(*, data=None, error_trace=None, filter_path=None, hint=None, human=None, name=None, pretty=None, size=None, body=None)

Suggest a user profile. Get suggestions for user profiles that match specified search criteria. NOTE: The user profile feature is designed only for use by Kibana and Elastic’s Observability, Enterprise Search, and Elastic Security solutions. Individual users and external applications should not call this API directly. Elastic reserves the right to change or remove this feature in future releases without prior notice.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-suggest-user-profile.html

Parameters:

  • data (str | Sequence[str] | None) – A comma-separated list of filters for the data field of the profile document. To return all content use data=*. To return a subset of content, use data=<key> to retrieve content nested under the specified <key>. By default, the API returns no data content. It is an error to specify data as both the query parameter and the request body field.

  • hint (Mapping[str, Any] | None) – Extra search criteria to improve relevance of the suggestion result. Profiles matching the spcified hint are ranked higher in the response. Profiles not matching the hint aren’t excluded from the response as long as the profile matches the name field query.

  • name (str | None) – A query string used to match name-related fields in user profile documents. Name-related fields are the user’s username, full_name, and email.

  • size (int | None) – The number of profiles to return.

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

  • body (Dict[str, Any] | None)

Return type:

ObjectApiResponse[Any]

update_api_key(*, id, error_trace=None, expiration=None, filter_path=None, human=None, metadata=None, pretty=None, role_descriptors=None, body=None)

Update an API key. Updates attributes of an existing API key. Users can only update API keys that they created or that were granted to them. Use this API to update API keys created by the create API Key or grant API Key APIs. If you need to apply the same update to many API keys, you can use bulk update API Keys to reduce overhead. It’s not possible to update expired API keys, or API keys that have been invalidated by invalidate API Key. This API supports updates to an API key’s access scope and metadata. The access scope of an API key is derived from the role_descriptors you specify in the request, and a snapshot of the owner user’s permissions at the time of the request. The snapshot of the owner’s permissions is updated automatically on every call. If you don’t specify role_descriptors in the request, a call to this API might still change the API key’s access scope. This change can occur if the owner user’s permissions have changed since the API key was created or last modified. To update another user’s API key, use the run_as feature to submit a request on behalf of another user. IMPORTANT: It’s not possible to use an API key as the authentication credential for this API. To update an API key, the owner user’s credentials are required.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-update-api-key.html

Parameters:

  • id (str) – The ID of the API key to update.

  • expiration (str | Literal[-1] | ~typing.Literal[0] | None) – Expiration time for the API key.

  • metadata (Mapping[str, Any] | None) – Arbitrary metadata that you want to associate with the API key. It supports nested data structure. Within the metadata object, keys beginning with _ are reserved for system usage.

  • role_descriptors (Mapping[str, Mapping[str, Any]] | None) – An array of role descriptors for this API key. This parameter is optional. When it is not specified or is an empty array, then the API key will have a point in time snapshot of permissions of the authenticated user. If you supply role descriptors then the resultant permissions would be an intersection of API keys permissions and authenticated user’s permissions thereby limiting the access scope for API keys. The structure of role descriptor is the same as the request for create role API. For more details, see create or update roles API.

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

  • body (Dict[str, Any] | None)

Return type:

ObjectApiResponse[Any]

update_cross_cluster_api_key(*, id, access=None, error_trace=None, expiration=None, filter_path=None, human=None, metadata=None, pretty=None, body=None)

Update a cross-cluster API key. Update the attributes of an existing cross-cluster API key, which is used for API key based remote cluster access. To use this API, you must have at least the manage_security cluster privilege. Users can only update API keys that they created. To update another user’s API key, use the run_as feature to submit a request on behalf of another user. IMPORTANT: It’s not possible to use an API key as the authentication credential for this API. To update an API key, the owner user’s credentials are required. It’s not possible to update expired API keys, or API keys that have been invalidated by the invalidate API key API. This API supports updates to an API key’s access scope, metadata, and expiration. The owner user’s information, such as the username and realm, is also updated automatically on every call. NOTE: This API cannot update REST API keys, which should be updated by either the update API key or bulk update API keys API.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-update-cross-cluster-api-key.html

Parameters:

  • id (str) – The ID of the cross-cluster API key to update.

  • access (Mapping[str, Any] | None) – The access to be granted to this API key. The access is composed of permissions for cross cluster search and cross cluster replication. At least one of them must be specified. When specified, the new access assignment fully replaces the previously assigned access.

  • expiration (str | Literal[-1] | ~typing.Literal[0] | None) – The expiration time for the API key. By default, API keys never expire. This property can be omitted to leave the value unchanged.

  • metadata (Mapping[str, Any] | None) – Arbitrary metadata that you want to associate with the API key. It supports nested data structure. Within the metadata object, keys beginning with _ are reserved for system usage. When specified, this information fully replaces metadata previously associated with the API key.

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

  • body (Dict[str, Any] | None)

Return type:

ObjectApiResponse[Any]

update_settings(*, error_trace=None, filter_path=None, human=None, master_timeout=None, pretty=None, security=None, security_profile=None, security_tokens=None, timeout=None, body=None)

Update security index settings. Update the user-configurable settings for the security internal index (.security and associated indices). Only a subset of settings are allowed to be modified, for example index.auto_expand_replicas and index.number_of_replicas. If a specific index is not in use on the system and settings are provided for it, the request will be rejected. This API does not yet support configuring the settings for indices before they are in use.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-update-settings.html

Parameters:

  • master_timeout (str | Literal[-1] | ~typing.Literal[0] | None) – The period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

  • security (Mapping[str, Any] | None) – Settings for the index used for most security configuration, including native realm users and roles configured with the API.

  • security_profile (Mapping[str, Any] | None) – Settings for the index used to store profile information.

  • security_tokens (Mapping[str, Any] | None) – Settings for the index used to store tokens.

  • timeout (str | Literal[-1] | ~typing.Literal[0] | None) – The period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

  • body (Dict[str, Any] | None)

Return type:

ObjectApiResponse[Any]

update_user_profile_data(*, uid, data=None, error_trace=None, filter_path=None, human=None, if_primary_term=None, if_seq_no=None, labels=None, pretty=None, refresh=None, body=None)

Update user profile data. Update specific data for the user profile that is associated with a unique ID. NOTE: The user profile feature is designed only for use by Kibana and Elastic’s Observability, Enterprise Search, and Elastic Security solutions. Individual users and external applications should not call this API directly. Elastic reserves the right to change or remove this feature in future releases without prior notice. To use this API, you must have one of the following privileges: * The manage_user_profile cluster privilege. * The update_profile_data global privilege for the namespaces that are referenced in the request. This API updates the labels and data fields of an existing user profile document with JSON objects. New keys and their values are added to the profile document and conflicting keys are replaced by data that’s included in the request. For both labels and data, content is namespaced by the top-level fields. The update_profile_data global privilege grants privileges for updating only the allowed namespaces.

https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-update-user-profile-data.html

Parameters:

  • uid (str) – A unique identifier for the user profile.

  • data (Mapping[str, Any] | None) – Non-searchable data that you want to associate with the user profile. This field supports a nested data structure. Within the data object, top-level keys cannot begin with an underscore (_) or contain a period (.). The data object is not searchable, but can be retrieved with the get user profile API.

  • if_primary_term (int | None) – Only perform the operation if the document has this primary term.

  • if_seq_no (int | None) – Only perform the operation if the document has this sequence number.

  • labels (Mapping[str, Any] | None) – Searchable data that you want to associate with the user profile. This field supports a nested data structure. Within the labels object, top-level keys cannot begin with an underscore (_) or contain a period (.).

  • refresh (bool | str | Literal['false', 'true', 'wait_for'] | None) – If ‘true’, Elasticsearch refreshes the affected shards to make this operation visible to search. If ‘wait_for’, it waits for a refresh to make this operation visible to search. If ‘false’, nothing is done with refreshes.

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

  • body (Dict[str, Any] | None)

Return type:

ObjectApiResponse[Any]