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)

Creates or updates the user profile on behalf of another user.

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

Parameters:
  • grant_type (Literal['access_token', 'password'] | str | None)

  • access_token (str | None)

  • password (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]

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

Enables authentication as a user and retrieve information about the authenticated user.

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

Parameters:
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)

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

https://www.elastic.co/guide/en/elasticsearch/reference/8.14/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 (Literal['false', 'true', 'wait_for'] | bool | str | 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 a subset or all entries from the API key cache.

https://www.elastic.co/guide/en/elasticsearch/reference/8.14/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)

Evicts application privileges from the native application privileges cache.

https://www.elastic.co/guide/en/elasticsearch/reference/8.14/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)

Evicts users from the user cache. Can completely clear the cache or evict specific users.

https://www.elastic.co/guide/en/elasticsearch/reference/8.14/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)

Evicts roles from the native role cache.

https://www.elastic.co/guide/en/elasticsearch/reference/8.14/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)

Evicts tokens from the service account token caches.

https://www.elastic.co/guide/en/elasticsearch/reference/8.14/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)

Creates an API key for access without requiring basic authentication.

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

Parameters:
  • expiration (Literal[-1] | ~typing.Literal[0] | str | 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 (Literal['false', 'true', 'wait_for'] | bool | str | 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_service_token(*, namespace, service, name=None, error_trace=None, filter_path=None, human=None, pretty=None, refresh=None)

Creates a service account token for access without requiring basic authentication.

https://www.elastic.co/guide/en/elasticsearch/reference/8.14/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 (Literal['false', 'true', 'wait_for'] | bool | str | 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_privileges(*, application, name, error_trace=None, filter_path=None, human=None, pretty=None, refresh=None)

Removes application privileges.

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

Parameters:
  • application (str) – Application name

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

  • refresh (Literal['false', 'true', 'wait_for'] | bool | str | 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)

Removes roles in the native realm.

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

Parameters:
  • name (str) – Role name

  • refresh (Literal['false', 'true', 'wait_for'] | bool | str | 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)

Removes role mappings.

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

Parameters:
  • name (str) – Role-mapping name

  • refresh (Literal['false', 'true', 'wait_for'] | bool | str | 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)

Deletes a service account token.

https://www.elastic.co/guide/en/elasticsearch/reference/8.14/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 (Literal['false', 'true', 'wait_for'] | bool | str | 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)

Deletes users from the native realm.

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

Parameters:
  • username (str) – username

  • refresh (Literal['false', 'true', 'wait_for'] | bool | str | 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)

Disables users in the native realm.

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

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

  • refresh (Literal['false', 'true', 'wait_for'] | bool | str | 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)

Disables a user profile so it’s not visible in user profile searches.

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

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

  • refresh (Literal['false', 'true', 'wait_for'] | bool | str | None) – If ‘true’, Elasticsearch refreshes 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’ 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(*, username, error_trace=None, filter_path=None, human=None, pretty=None, refresh=None)

Enables users in the native realm.

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

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

  • refresh (Literal['false', 'true', 'wait_for'] | bool | str | 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)

Enables a user profile so it’s visible in user profile searches.

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

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

  • refresh (Literal['false', 'true', 'wait_for'] | bool | str | None) – If ‘true’, Elasticsearch refreshes 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’ do nothing 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)

Allows a kibana instance to configure itself to communicate with a secured elasticsearch cluster.

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

Parameters:
Return type:

ObjectApiResponse[Any]

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

Allows a new node to enroll to an existing cluster with security enabled.

https://www.elastic.co/guide/en/elasticsearch/reference/8.14/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)

Retrieves information for one or more API keys.

https://www.elastic.co/guide/en/elasticsearch/reference/8.14/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)

Retrieves 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.14/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)

Retrieves application privileges.

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

Parameters:
Return type:

ObjectApiResponse[Any]

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

Retrieves roles in the native realm.

https://www.elastic.co/guide/en/elasticsearch/reference/8.14/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)

Retrieves role mappings.

https://www.elastic.co/guide/en/elasticsearch/reference/8.14/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)

Retrieves information about service accounts.

https://www.elastic.co/guide/en/elasticsearch/reference/8.14/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)

Retrieves information of all service credentials for a service account.

https://www.elastic.co/guide/en/elasticsearch/reference/8.14/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_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)

Creates a bearer token for access without requiring basic authentication.

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

Parameters:
  • grant_type (Literal['_kerberos', 'client_credentials', 'password', 'refresh_token'] | str | 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)

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

https://www.elastic.co/guide/en/elasticsearch/reference/8.14/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)

Retrieves security privileges for the logged in user.

https://www.elastic.co/guide/en/elasticsearch/reference/8.14/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)

Retrieves user profiles for the given unique ID(s).

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

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

  • data (str | Sequence[str] | None) – 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)

Creates an API key on behalf of another user.

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

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

  • grant_type (Literal['access_token', 'password'] | str | 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)

Determines whether the specified user has a specified list of privileges.

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

Parameters:
  • user (str | None) – Username

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

  • cluster (Sequence[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_text_structure', 'monitor_transform', 'monitor_watcher', 'none', 'post_behavioral_analytics_event', 'read_ccr', 'read_connector_secrets', 'read_fleet_secrets', 'read_ilm', 'read_pipeline', 'read_security', 'read_slm', 'transport_client', 'write_connector_secrets', 'write_fleet_secrets'] | str] | 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)

Determines whether the users associated with the specified profile IDs have all the requested privileges.

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

Parameters:
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)

Invalidates one or more API keys.

https://www.elastic.co/guide/en/elasticsearch/reference/8.14/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)

Invalidates one or more access tokens or refresh tokens.

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

Parameters:
Return type:

ObjectApiResponse[Any]

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

Adds or updates application privileges.

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

Parameters:
  • privileges (Mapping[str, Mapping[str, Mapping[str, Any]]] | None)

  • refresh (Literal['false', 'true', 'wait_for'] | bool | str | 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.

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

  • error_trace (bool | None)

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

  • human (bool | None)

  • pretty (bool | None)

Return type:

ObjectApiResponse[Any]

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

Adds and updates roles in the native realm.

https://www.elastic.co/guide/en/elasticsearch/reference/8.14/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[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_text_structure', 'monitor_transform', 'monitor_watcher', 'none', 'post_behavioral_analytics_event', 'read_ccr', 'read_connector_secrets', 'read_fleet_secrets', 'read_ilm', 'read_pipeline', 'read_security', 'read_slm', 'transport_client', 'write_connector_secrets', 'write_fleet_secrets'] | str] | None) – A list of cluster privileges. These privileges define the cluster-level actions for users with this role.

  • 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 (Literal['false', 'true', 'wait_for'] | bool | str | 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.

  • run_as (Sequence[str] | None) – A list of users that the owners of this role can impersonate.

  • 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)

Creates and updates role mappings.

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

Parameters:
  • name (str) – Role-mapping name

  • enabled (bool | None)

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

  • refresh (Literal['false', 'true', 'wait_for'] | bool | str | 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)

Adds and updates users in the native realm. These users are commonly referred to as native users.

https://www.elastic.co/guide/en/elasticsearch/reference/8.14/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 (Literal['false', 'true', 'wait_for'] | bool | str | 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)

Retrieves information for API keys using a subset of query DSL

https://www.elastic.co/guide/en/elasticsearch/reference/8.14/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]

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

Exchanges a SAML Response message for an Elasticsearch access token and refresh token pair

https://www.elastic.co/guide/en/elasticsearch/reference/8.14/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)

Verifies the logout response sent from the SAML IdP

https://www.elastic.co/guide/en/elasticsearch/reference/8.14/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)

Consumes a SAML LogoutRequest

https://www.elastic.co/guide/en/elasticsearch/reference/8.14/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)

Invalidates an access token and a refresh token that were generated via the SAML Authenticate API

https://www.elastic.co/guide/en/elasticsearch/reference/8.14/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)

Creates a SAML authentication request

https://www.elastic.co/guide/en/elasticsearch/reference/8.14/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)

Generates SAML metadata for the Elastic stack SAML 2.0 Service Provider

https://www.elastic.co/guide/en/elasticsearch/reference/8.14/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)

Get suggestions for user profiles that match specified search criteria.

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

Parameters:
  • data (str | Sequence[str] | None) – 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.

  • 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 don’t exclude the profile from the response as long as the profile matches the name field query.

  • name (str | None) – 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) – 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)

Updates attributes of an existing API key.

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

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

  • expiration (Literal[-1] | ~typing.Literal[0] | str | 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_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 application specific data for the user profile of the given unique ID.

https://www.elastic.co/guide/en/elasticsearch/reference/8.14/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.

  • 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.

  • refresh (Literal['false', 'true', 'wait_for'] | bool | str | None) – If ‘true’, Elasticsearch refreshes 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’ 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]