elasticsearch-js/docs/reference/security.asciidoc

[[reference-security]]
== client.security

////////
===========================================================================================================================
||                                                                                                                       ||
||                                                                                                                       ||
||                                                                                                                       ||
||        ██████╗ ███████╗ █████╗ ██████╗ ███╗   ███╗███████╗                                                            ||
||        ██╔══██╗██╔════╝██╔══██╗██╔══██╗████╗ ████║██╔════╝                                                            ||
||        ██████╔╝█████╗  ███████║██║  ██║██╔████╔██║█████╗                                                              ||
||        ██╔══██╗██╔══╝  ██╔══██║██║  ██║██║╚██╔╝██║██╔══╝                                                              ||
||        ██║  ██║███████╗██║  ██║██████╔╝██║ ╚═╝ ██║███████╗                                                            ||
||        ╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝╚═════╝ ╚═╝     ╚═╝╚══════╝                                                            ||
||                                                                                                                       ||
||                                                                                                                       ||
||    This file is autogenerated, DO NOT send pull requests that changes this file directly.                             ||
||    You should update the script that does the generation, which can be found in:                                      ||
||    https://github.com/elastic/elastic-client-generator-js                                                             ||
||                                                                                                                       ||
||    You can run the script with the following command:                                                                 ||
||       npm run elasticsearch -- --version <version>                                                                    ||
||                                                                                                                       ||
||                                                                                                                       ||
||                                                                                                                       ||
===========================================================================================================================
////////
++++
<style>
.lang-ts a.xref {
  text-decoration: underline !important;
}
</style>
++++


[discrete]
[[client.security.activateUserProfile]]
== `client.security.activateUserProfile()`

Activate a user profile. Create or update a user profile on behalf of another user.

{ref}/security-api-activate-user-profile.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityActivateUserProfileRequest, options?: TransportRequestOptions) => Promise<SecurityActivateUserProfileResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecurityActivateUserProfileRequest extends <<RequestBase>> {
  access_token?: string
  grant_type: <<SecurityGrantType>>
  password?: string
  username?: string
}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
type SecurityActivateUserProfileResponse = <<SecurityUserProfileWithMetadata>>

----


[discrete]
[[client.security.authenticate]]
== `client.security.authenticate()`

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.

{ref}/security-api-authenticate.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityAuthenticateRequest, options?: TransportRequestOptions) => Promise<SecurityAuthenticateResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecurityAuthenticateRequest extends <<RequestBase>> {}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
interface SecurityAuthenticateResponse {
  api_key?: SecurityAuthenticateAuthenticateApiKey
  authentication_realm: <<SecurityRealmInfo>>
  email?: string | null
  full_name?: <<Name>> | null
  lookup_realm: <<SecurityRealmInfo>>
  metadata: <<Metadata>>
  roles: string[]
  username: <<Username>>
  enabled: boolean
  authentication_type: string
  token?: SecurityAuthenticateToken
}

----


[discrete]
[[client.security.bulkDeleteRole]]
== `client.security.bulkDeleteRole()`

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.

{ref}/security-api-bulk-delete-role.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityBulkDeleteRoleRequest, options?: TransportRequestOptions) => Promise<SecurityBulkDeleteRoleResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecurityBulkDeleteRoleRequest extends <<RequestBase>> {
  refresh?: <<Refresh>>
  names: string[]
}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
interface SecurityBulkDeleteRoleResponse {
  deleted?: string[]
  not_found?: string[]
  errors?: <<SecurityBulkError>>
}

----


[discrete]
[[client.security.bulkPutRole]]
== `client.security.bulkPutRole()`

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.

{ref}/security-api-bulk-put-role.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityBulkPutRoleRequest, options?: TransportRequestOptions) => Promise<SecurityBulkPutRoleResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecurityBulkPutRoleRequest extends <<RequestBase>> {
  refresh?: <<Refresh>>
  roles: Record<string, <<SecurityRoleDescriptor>>>
}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
interface SecurityBulkPutRoleResponse {
  created?: string[]
  updated?: string[]
  noop?: string[]
  errors?: <<SecurityBulkError>>
}

----


[discrete]
[[client.security.bulkUpdateApiKeys]]
== `client.security.bulkUpdateApiKeys()`

Updates the attributes of multiple existing API keys.

{ref}/security-api-bulk-update-api-keys.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityBulkUpdateApiKeysRequest, options?: TransportRequestOptions) => Promise<SecurityBulkUpdateApiKeysResponse>
----

[discrete]
[[client.security.changePassword]]
== `client.security.changePassword()`

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

{ref}/security-api-change-password.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityChangePasswordRequest, options?: TransportRequestOptions) => Promise<SecurityChangePasswordResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecurityChangePasswordRequest extends <<RequestBase>> {
  username?: <<Username>>
  refresh?: <<Refresh>>
  password?: <<Password>>
  password_hash?: string
}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
interface SecurityChangePasswordResponse {}

----


[discrete]
[[client.security.clearApiKeyCache]]
== `client.security.clearApiKeyCache()`

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.

{ref}/security-api-clear-api-key-cache.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityClearApiKeyCacheRequest, options?: TransportRequestOptions) => Promise<SecurityClearApiKeyCacheResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecurityClearApiKeyCacheRequest extends <<RequestBase>> {
  ids: <<Ids>>
}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
interface SecurityClearApiKeyCacheResponse {
  _nodes: <<NodeStatistics>>
  cluster_name: <<Name>>
  nodes: Record<string, <<SecurityClusterNode>>>
}

----


[discrete]
[[client.security.clearCachedPrivileges]]
== `client.security.clearCachedPrivileges()`

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.

{ref}/security-api-clear-privilege-cache.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityClearCachedPrivilegesRequest, options?: TransportRequestOptions) => Promise<SecurityClearCachedPrivilegesResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecurityClearCachedPrivilegesRequest extends <<RequestBase>> {
  application: <<Name>>
}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
interface SecurityClearCachedPrivilegesResponse {
  _nodes: <<NodeStatistics>>
  cluster_name: <<Name>>
  nodes: Record<string, <<SecurityClusterNode>>>
}

----


[discrete]
[[client.security.clearCachedRealms]]
== `client.security.clearCachedRealms()`

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

{ref}/security-api-clear-cache.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityClearCachedRealmsRequest, options?: TransportRequestOptions) => Promise<SecurityClearCachedRealmsResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecurityClearCachedRealmsRequest extends <<RequestBase>> {
  realms: <<Names>>
  usernames?: string[]
}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
interface SecurityClearCachedRealmsResponse {
  _nodes: <<NodeStatistics>>
  cluster_name: <<Name>>
  nodes: Record<string, <<SecurityClusterNode>>>
}

----


[discrete]
[[client.security.clearCachedRoles]]
== `client.security.clearCachedRoles()`

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

{ref}/security-api-clear-role-cache.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityClearCachedRolesRequest, options?: TransportRequestOptions) => Promise<SecurityClearCachedRolesResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecurityClearCachedRolesRequest extends <<RequestBase>> {
  name: <<Names>>
}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
interface SecurityClearCachedRolesResponse {
  _nodes: <<NodeStatistics>>
  cluster_name: <<Name>>
  nodes: Record<string, <<SecurityClusterNode>>>
}

----


[discrete]
[[client.security.clearCachedServiceTokens]]
== `client.security.clearCachedServiceTokens()`

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

{ref}/security-api-clear-service-token-caches.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityClearCachedServiceTokensRequest, options?: TransportRequestOptions) => Promise<SecurityClearCachedServiceTokensResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecurityClearCachedServiceTokensRequest extends <<RequestBase>> {
  namespace: <<Namespace>>
  service: <<Service>>
  name: <<Names>>
}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
interface SecurityClearCachedServiceTokensResponse {
  _nodes: <<NodeStatistics>>
  cluster_name: <<Name>>
  nodes: Record<string, <<SecurityClusterNode>>>
}

----


[discrete]
[[client.security.createApiKey]]
== `client.security.createApiKey()`

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.

{ref}/security-api-create-api-key.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityCreateApiKeyRequest, options?: TransportRequestOptions) => Promise<SecurityCreateApiKeyResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecurityCreateApiKeyRequest extends <<RequestBase>> {
  refresh?: <<Refresh>>
  expiration?: <<Duration>>
  name?: <<Name>>
  role_descriptors?: Record<string, <<SecurityRoleDescriptor>>>
  metadata?: <<Metadata>>
}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
interface SecurityCreateApiKeyResponse {
  api_key: string
  expiration?: <<long>>
  id: <<Id>>
  name: <<Name>>
  encoded: string
}

----


[discrete]
[[client.security.createCrossClusterApiKey]]
== `client.security.createCrossClusterApiKey()`

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.

{ref}/security-api-create-cross-cluster-api-key.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityCreateCrossClusterApiKeyRequest, options?: TransportRequestOptions) => Promise<SecurityCreateCrossClusterApiKeyResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecurityCreateCrossClusterApiKeyRequest extends <<RequestBase>> {
  access: <<SecurityAccess>>
  expiration?: <<Duration>>
  metadata?: <<Metadata>>
  name: <<Name>>
}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
interface SecurityCreateCrossClusterApiKeyResponse {
  api_key: string
  expiration?: <<DurationValue>><<<UnitMillis>>>
  id: <<Id>>
  name: <<Name>>
  encoded: string
}

----


[discrete]
[[client.security.createServiceToken]]
== `client.security.createServiceToken()`

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

{ref}/security-api-create-service-token.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityCreateServiceTokenRequest, options?: TransportRequestOptions) => Promise<SecurityCreateServiceTokenResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecurityCreateServiceTokenRequest extends <<RequestBase>> {
  namespace: <<Namespace>>
  service: <<Service>>
  name?: <<Name>>
  refresh?: <<Refresh>>
}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
interface SecurityCreateServiceTokenResponse {
  created: boolean
  token: SecurityCreateServiceTokenToken
}

----


[discrete]
[[client.security.deletePrivileges]]
== `client.security.deletePrivileges()`

Delete application privileges.

{ref}/security-api-delete-privilege.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityDeletePrivilegesRequest, options?: TransportRequestOptions) => Promise<SecurityDeletePrivilegesResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecurityDeletePrivilegesRequest extends <<RequestBase>> {
  application: <<Name>>
  name: <<Names>>
  refresh?: <<Refresh>>
}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
type SecurityDeletePrivilegesResponse = Record<string, Record<string, SecurityDeletePrivilegesFoundStatus>>

----


[discrete]
[[client.security.deleteRole]]
== `client.security.deleteRole()`

Delete roles. Delete roles in the native realm.

{ref}/security-api-delete-role.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityDeleteRoleRequest, options?: TransportRequestOptions) => Promise<SecurityDeleteRoleResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecurityDeleteRoleRequest extends <<RequestBase>> {
  name: <<Name>>
  refresh?: <<Refresh>>
}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
interface SecurityDeleteRoleResponse {
  found: boolean
}

----


[discrete]
[[client.security.deleteRoleMapping]]
== `client.security.deleteRoleMapping()`

Delete role mappings.

{ref}/security-api-delete-role-mapping.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityDeleteRoleMappingRequest, options?: TransportRequestOptions) => Promise<SecurityDeleteRoleMappingResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecurityDeleteRoleMappingRequest extends <<RequestBase>> {
  name: <<Name>>
  refresh?: <<Refresh>>
}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
interface SecurityDeleteRoleMappingResponse {
  found: boolean
}

----


[discrete]
[[client.security.deleteServiceToken]]
== `client.security.deleteServiceToken()`

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

{ref}/security-api-delete-service-token.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityDeleteServiceTokenRequest, options?: TransportRequestOptions) => Promise<SecurityDeleteServiceTokenResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecurityDeleteServiceTokenRequest extends <<RequestBase>> {
  namespace: <<Namespace>>
  service: <<Service>>
  name: <<Name>>
  refresh?: <<Refresh>>
}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
interface SecurityDeleteServiceTokenResponse {
  found: boolean
}

----


[discrete]
[[client.security.deleteUser]]
== `client.security.deleteUser()`

Delete users. Delete users from the native realm.

{ref}/security-api-delete-user.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityDeleteUserRequest, options?: TransportRequestOptions) => Promise<SecurityDeleteUserResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecurityDeleteUserRequest extends <<RequestBase>> {
  username: <<Username>>
  refresh?: <<Refresh>>
}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
interface SecurityDeleteUserResponse {
  found: boolean
}

----


[discrete]
[[client.security.disableUser]]
== `client.security.disableUser()`

Disable users. Disable users in the native realm.

{ref}/security-api-disable-user.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityDisableUserRequest, options?: TransportRequestOptions) => Promise<SecurityDisableUserResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecurityDisableUserRequest extends <<RequestBase>> {
  username: <<Username>>
  refresh?: <<Refresh>>
}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
interface SecurityDisableUserResponse {}

----


[discrete]
[[client.security.disableUserProfile]]
== `client.security.disableUserProfile()`

Disable a user profile. Disable user profiles so that they are not visible in user profile searches.

{ref}/security-api-disable-user-profile.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityDisableUserProfileRequest, options?: TransportRequestOptions) => Promise<SecurityDisableUserProfileResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecurityDisableUserProfileRequest extends <<RequestBase>> {
  uid: <<SecurityUserProfileId>>
  refresh?: <<Refresh>>
}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
type SecurityDisableUserProfileResponse = <<AcknowledgedResponseBase>>

----


[discrete]
[[client.security.enableUser]]
== `client.security.enableUser()`

Enable users. Enable users in the native realm.

{ref}/security-api-enable-user.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityEnableUserRequest, options?: TransportRequestOptions) => Promise<SecurityEnableUserResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecurityEnableUserRequest extends <<RequestBase>> {
  username: <<Username>>
  refresh?: <<Refresh>>
}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
interface SecurityEnableUserResponse {}

----


[discrete]
[[client.security.enableUserProfile]]
== `client.security.enableUserProfile()`

Enable a user profile. Enable user profiles to make them visible in user profile searches.

{ref}/security-api-enable-user-profile.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityEnableUserProfileRequest, options?: TransportRequestOptions) => Promise<SecurityEnableUserProfileResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecurityEnableUserProfileRequest extends <<RequestBase>> {
  uid: <<SecurityUserProfileId>>
  refresh?: <<Refresh>>
}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
type SecurityEnableUserProfileResponse = <<AcknowledgedResponseBase>>

----


[discrete]
[[client.security.enrollKibana]]
== `client.security.enrollKibana()`

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

{ref}/security-api-kibana-enrollment.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityEnrollKibanaRequest, options?: TransportRequestOptions) => Promise<SecurityEnrollKibanaResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecurityEnrollKibanaRequest extends <<RequestBase>> {}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
interface SecurityEnrollKibanaResponse {
  token: SecurityEnrollKibanaToken
  http_ca: string
}

----


[discrete]
[[client.security.enrollNode]]
== `client.security.enrollNode()`

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

{ref}/security-api-node-enrollment.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityEnrollNodeRequest, options?: TransportRequestOptions) => Promise<SecurityEnrollNodeResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecurityEnrollNodeRequest extends <<RequestBase>> {}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
interface SecurityEnrollNodeResponse {
  http_ca_key: string
  http_ca_cert: string
  transport_ca_cert: string
  transport_key: string
  transport_cert: string
  nodes_addresses: string[]
}

----


[discrete]
[[client.security.getApiKey]]
== `client.security.getApiKey()`

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.

{ref}/security-api-get-api-key.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityGetApiKeyRequest, options?: TransportRequestOptions) => Promise<SecurityGetApiKeyResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecurityGetApiKeyRequest extends <<RequestBase>> {
  id?: <<Id>>
  name?: <<Name>>
  owner?: boolean
  realm_name?: <<Name>>
  username?: <<Username>>
  with_limited_by?: boolean
  active_only?: boolean
  with_profile_uid?: boolean
}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
interface SecurityGetApiKeyResponse {
  api_keys: <<SecurityApiKey>>[]
}

----


[discrete]
[[client.security.getBuiltinPrivileges]]
== `client.security.getBuiltinPrivileges()`

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

{ref}/security-api-get-builtin-privileges.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityGetBuiltinPrivilegesRequest, options?: TransportRequestOptions) => Promise<SecurityGetBuiltinPrivilegesResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecurityGetBuiltinPrivilegesRequest extends <<RequestBase>> {}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
interface SecurityGetBuiltinPrivilegesResponse {
  cluster: <<SecurityClusterPrivilege>>[]
  index: <<IndexName>>[]
  remote_cluster: <<SecurityRemoteClusterPrivilege>>[]
}

----


[discrete]
[[client.security.getPrivileges]]
== `client.security.getPrivileges()`

Get application privileges.

{ref}/security-api-get-privileges.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityGetPrivilegesRequest, options?: TransportRequestOptions) => Promise<SecurityGetPrivilegesResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecurityGetPrivilegesRequest extends <<RequestBase>> {
  application?: <<Name>>
  name?: <<Names>>
}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
type SecurityGetPrivilegesResponse = Record<string, Record<string, SecurityPutPrivilegesActions>>

----


[discrete]
[[client.security.getRole]]
== `client.security.getRole()`

Get roles. Get roles in the native realm.

{ref}/security-api-get-role.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityGetRoleRequest, options?: TransportRequestOptions) => Promise<SecurityGetRoleResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecurityGetRoleRequest extends <<RequestBase>> {
  name?: <<Names>>
}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
type SecurityGetRoleResponse = Record<string, SecurityGetRoleRole>

----


[discrete]
[[client.security.getRoleMapping]]
== `client.security.getRoleMapping()`

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.

{ref}/security-api-get-role-mapping.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityGetRoleMappingRequest, options?: TransportRequestOptions) => Promise<SecurityGetRoleMappingResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecurityGetRoleMappingRequest extends <<RequestBase>> {
  name?: <<Names>>
}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
type SecurityGetRoleMappingResponse = Record<string, <<SecurityRoleMapping>>>

----


[discrete]
[[client.security.getServiceAccounts]]
== `client.security.getServiceAccounts()`

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

{ref}/security-api-get-service-accounts.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityGetServiceAccountsRequest, options?: TransportRequestOptions) => Promise<SecurityGetServiceAccountsResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecurityGetServiceAccountsRequest extends <<RequestBase>> {
  namespace?: <<Namespace>>
  service?: <<Service>>
}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
type SecurityGetServiceAccountsResponse = Record<string, SecurityGetServiceAccountsRoleDescriptorWrapper>

----


[discrete]
[[client.security.getServiceCredentials]]
== `client.security.getServiceCredentials()`

Get service account credentials.

{ref}/security-api-get-service-credentials.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityGetServiceCredentialsRequest, options?: TransportRequestOptions) => Promise<SecurityGetServiceCredentialsResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecurityGetServiceCredentialsRequest extends <<RequestBase>> {
  namespace: <<Namespace>>
  service: <<Name>>
}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
interface SecurityGetServiceCredentialsResponse {
  service_account: string
  count: <<integer>>
  tokens: Record<string, <<Metadata>>>
  nodes_credentials: SecurityGetServiceCredentialsNodesCredentials
}

----


[discrete]
[[client.security.getSettings]]
== `client.security.getSettings()`

Retrieve settings for the security system indices

{ref}/security-api-get-settings.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityGetSettingsRequest, options?: TransportRequestOptions) => Promise<SecurityGetSettingsResponse>
----

[discrete]
[[client.security.getToken]]
== `client.security.getToken()`

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

{ref}/security-api-get-token.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityGetTokenRequest, options?: TransportRequestOptions) => Promise<SecurityGetTokenResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecurityGetTokenRequest extends <<RequestBase>> {
  grant_type?: SecurityGetTokenAccessTokenGrantType
  scope?: string
  password?: <<Password>>
  kerberos_ticket?: string
  refresh_token?: string
  username?: <<Username>>
}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
interface SecurityGetTokenResponse {
  access_token: string
  expires_in: <<long>>
  scope?: string
  type: string
  refresh_token?: string
  kerberos_authentication_response_token?: string
  authentication: SecurityGetTokenAuthenticatedUser
}

----


[discrete]
[[client.security.getUser]]
== `client.security.getUser()`

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

{ref}/security-api-get-user.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityGetUserRequest, options?: TransportRequestOptions) => Promise<SecurityGetUserResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecurityGetUserRequest extends <<RequestBase>> {
  username?: <<Username>> | <<Username>>[]
  with_profile_uid?: boolean
}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
type SecurityGetUserResponse = Record<string, <<SecurityUser>>>

----


[discrete]
[[client.security.getUserPrivileges]]
== `client.security.getUserPrivileges()`

Get user privileges.

{ref}/security-api-get-user-privileges.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityGetUserPrivilegesRequest, options?: TransportRequestOptions) => Promise<SecurityGetUserPrivilegesResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecurityGetUserPrivilegesRequest extends <<RequestBase>> {
  application?: <<Name>>
  priviledge?: <<Name>>
  username?: <<Name>> | null
}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
interface SecurityGetUserPrivilegesResponse {
  applications: <<SecurityApplicationPrivileges>>[]
  cluster: string[]
  global: <<SecurityGlobalPrivilege>>[]
  indices: <<SecurityUserIndicesPrivileges>>[]
  run_as: string[]
}

----


[discrete]
[[client.security.getUserProfile]]
== `client.security.getUserProfile()`

Get a user profile. Get a user's profile using the unique profile ID.

{ref}/security-api-get-user-profile.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityGetUserProfileRequest, options?: TransportRequestOptions) => Promise<SecurityGetUserProfileResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecurityGetUserProfileRequest extends <<RequestBase>> {
  uid: <<SecurityUserProfileId>> | <<SecurityUserProfileId>>[]
  data?: string | string[]
}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
interface SecurityGetUserProfileResponse {
  profiles: <<SecurityUserProfileWithMetadata>>[]
  errors?: SecurityGetUserProfileGetUserProfileErrors
}

----


[discrete]
[[client.security.grantApiKey]]
== `client.security.grantApiKey()`

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.

{ref}/security-api-grant-api-key.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityGrantApiKeyRequest, options?: TransportRequestOptions) => Promise<SecurityGrantApiKeyResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecurityGrantApiKeyRequest extends <<RequestBase>> {
  api_key: SecurityGrantApiKeyGrantApiKey
  grant_type: SecurityGrantApiKeyApiKeyGrantType
  access_token?: string
  username?: <<Username>>
  password?: <<Password>>
  run_as?: <<Username>>
}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
interface SecurityGrantApiKeyResponse {
  api_key: string
  id: <<Id>>
  name: <<Name>>
  expiration?: <<EpochTime>><<<UnitMillis>>>
  encoded: string
}

----


[discrete]
[[client.security.hasPrivileges]]
== `client.security.hasPrivileges()`

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

{ref}/security-api-has-privileges.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityHasPrivilegesRequest, options?: TransportRequestOptions) => Promise<SecurityHasPrivilegesResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecurityHasPrivilegesRequest extends <<RequestBase>> {
  user?: <<Name>>
  application?: SecurityHasPrivilegesApplicationPrivilegesCheck[]
  cluster?: <<SecurityClusterPrivilege>>[]
  index?: SecurityHasPrivilegesIndexPrivilegesCheck[]
}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
interface SecurityHasPrivilegesResponse {
  application: SecurityHasPrivilegesApplicationsPrivileges
  cluster: Record<string, boolean>
  has_all_requested: boolean
  index: Record<<<IndexName>>, SecurityHasPrivilegesPrivileges>
  username: <<Username>>
}

----


[discrete]
[[client.security.hasPrivilegesUserProfile]]
== `client.security.hasPrivilegesUserProfile()`

Check user profile privileges. Determine whether the users associated with the specified user profile IDs have all the requested privileges.

{ref}/security-api-has-privileges-user-profile.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityHasPrivilegesUserProfileRequest, options?: TransportRequestOptions) => Promise<SecurityHasPrivilegesUserProfileResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecurityHasPrivilegesUserProfileRequest extends <<RequestBase>> {
  uids: <<SecurityUserProfileId>>[]
  privileges: SecurityHasPrivilegesUserProfilePrivilegesCheck
}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
interface SecurityHasPrivilegesUserProfileResponse {
  has_privilege_uids: <<SecurityUserProfileId>>[]
  errors?: SecurityHasPrivilegesUserProfileHasPrivilegesUserProfileErrors
}

----


[discrete]
[[client.security.invalidateApiKey]]
== `client.security.invalidateApiKey()`

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.

{ref}/security-api-invalidate-api-key.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityInvalidateApiKeyRequest, options?: TransportRequestOptions) => Promise<SecurityInvalidateApiKeyResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecurityInvalidateApiKeyRequest extends <<RequestBase>> {
  id?: <<Id>>
  ids?: <<Id>>[]
  name?: <<Name>>
  owner?: boolean
  realm_name?: string
  username?: <<Username>>
}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
interface SecurityInvalidateApiKeyResponse {
  error_count: <<integer>>
  error_details?: <<ErrorCause>>[]
  invalidated_api_keys: string[]
  previously_invalidated_api_keys: string[]
}

----


[discrete]
[[client.security.invalidateToken]]
== `client.security.invalidateToken()`

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.

{ref}/security-api-invalidate-token.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityInvalidateTokenRequest, options?: TransportRequestOptions) => Promise<SecurityInvalidateTokenResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecurityInvalidateTokenRequest extends <<RequestBase>> {
  token?: string
  refresh_token?: string
  realm_name?: <<Name>>
  username?: <<Username>>
}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
interface SecurityInvalidateTokenResponse {
  error_count: <<long>>
  error_details?: <<ErrorCause>>[]
  invalidated_tokens: <<long>>
  previously_invalidated_tokens: <<long>>
}

----


[discrete]
[[client.security.oidcAuthenticate]]
== `client.security.oidcAuthenticate()`

Exchanges an OpenID Connection authentication response message for an Elasticsearch access token and refresh token pair

{ref}/security-api-oidc-authenticate.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityOidcAuthenticateRequest, options?: TransportRequestOptions) => Promise<SecurityOidcAuthenticateResponse>
----

[discrete]
[[client.security.oidcLogout]]
== `client.security.oidcLogout()`

Invalidates a refresh token and access token that was generated from the OpenID Connect Authenticate API

{ref}/security-api-oidc-logout.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityOidcLogoutRequest, options?: TransportRequestOptions) => Promise<SecurityOidcLogoutResponse>
----

[discrete]
[[client.security.oidcPrepareAuthentication]]
== `client.security.oidcPrepareAuthentication()`

Creates an OAuth 2.0 authentication request as a URL string

{ref}/security-api-oidc-prepare-authentication.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityOidcPrepareAuthenticationRequest, options?: TransportRequestOptions) => Promise<SecurityOidcPrepareAuthenticationResponse>
----

[discrete]
[[client.security.putPrivileges]]
== `client.security.putPrivileges()`

Create or update application privileges.

{ref}/security-api-put-privileges.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityPutPrivilegesRequest, options?: TransportRequestOptions) => Promise<SecurityPutPrivilegesResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecurityPutPrivilegesRequest extends <<RequestBase>> {
  refresh?: <<Refresh>>
  privileges?: Record<string, Record<string, SecurityPutPrivilegesActions>>
}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
type SecurityPutPrivilegesResponse = Record<string, Record<string, <<SecurityCreatedStatus>>>>

----


[discrete]
[[client.security.putRole]]
== `client.security.putRole()`

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.

{ref}/security-api-put-role.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityPutRoleRequest, options?: TransportRequestOptions) => Promise<SecurityPutRoleResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecurityPutRoleRequest extends <<RequestBase>> {
  name: <<Name>>
  refresh?: <<Refresh>>
  applications?: <<SecurityApplicationPrivileges>>[]
  cluster?: <<SecurityClusterPrivilege>>[]
  global?: Record<string, any>
  indices?: <<SecurityIndicesPrivileges>>[]
  remote_indices?: <<SecurityRemoteIndicesPrivileges>>[]
  remote_cluster?: <<SecurityRemoteClusterPrivileges>>[]
  metadata?: <<Metadata>>
  run_as?: string[]
  description?: string
  transient_metadata?: Record<string, any>
}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
interface SecurityPutRoleResponse {
  role: <<SecurityCreatedStatus>>
}

----


[discrete]
[[client.security.putRoleMapping]]
== `client.security.putRoleMapping()`

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.

{ref}/security-api-put-role-mapping.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityPutRoleMappingRequest, options?: TransportRequestOptions) => Promise<SecurityPutRoleMappingResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecurityPutRoleMappingRequest extends <<RequestBase>> {
  name: <<Name>>
  refresh?: <<Refresh>>
  enabled?: boolean
  metadata?: <<Metadata>>
  roles?: string[]
  role_templates?: <<SecurityRoleTemplate>>[]
  rules?: <<SecurityRoleMappingRule>>
  run_as?: string[]
}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
interface SecurityPutRoleMappingResponse {
  created?: boolean
  role_mapping: <<SecurityCreatedStatus>>
}

----


[discrete]
[[client.security.putUser]]
== `client.security.putUser()`

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.

{ref}/security-api-put-user.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityPutUserRequest, options?: TransportRequestOptions) => Promise<SecurityPutUserResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecurityPutUserRequest extends <<RequestBase>> {
  username: <<Username>>
  refresh?: <<Refresh>>
  email?: string | null
  full_name?: string | null
  metadata?: <<Metadata>>
  password?: <<Password>>
  password_hash?: string
  roles?: string[]
  enabled?: boolean
}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
interface SecurityPutUserResponse {
  created: boolean
}

----


[discrete]
[[client.security.queryApiKeys]]
== `client.security.queryApiKeys()`

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.

{ref}/security-api-query-api-key.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityQueryApiKeysRequest, options?: TransportRequestOptions) => Promise<SecurityQueryApiKeysResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecurityQueryApiKeysRequest extends <<RequestBase>> {
  with_limited_by?: boolean
  with_profile_uid?: boolean
  typed_keys?: boolean
  aggregations?: Record<string, SecurityQueryApiKeysApiKeyAggregationContainer>
  pass:[/**] @alias aggregations */
  aggs?: Record<string, SecurityQueryApiKeysApiKeyAggregationContainer>
  query?: SecurityQueryApiKeysApiKeyQueryContainer
  from?: <<integer>>
  sort?: <<Sort>>
  size?: <<integer>>
  search_after?: <<SortResults>>
}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
interface SecurityQueryApiKeysResponse {
  total: <<integer>>
  count: <<integer>>
  api_keys: <<SecurityApiKey>>[]
  aggregations?: Record<<<AggregateName>>, SecurityQueryApiKeysApiKeyAggregate>
}

----


[discrete]
[[client.security.queryRole]]
== `client.security.queryRole()`

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

{ref}/security-api-query-role.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityQueryRoleRequest, options?: TransportRequestOptions) => Promise<SecurityQueryRoleResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecurityQueryRoleRequest extends <<RequestBase>> {
  query?: SecurityQueryRoleRoleQueryContainer
  from?: <<integer>>
  sort?: <<Sort>>
  size?: <<integer>>
  search_after?: <<SortResults>>
}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
interface SecurityQueryRoleResponse {
  total: <<integer>>
  count: <<integer>>
  roles: SecurityQueryRoleQueryRole[]
}

----


[discrete]
[[client.security.queryUser]]
== `client.security.queryUser()`

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

{ref}/security-api-query-user.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityQueryUserRequest, options?: TransportRequestOptions) => Promise<SecurityQueryUserResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecurityQueryUserRequest extends <<RequestBase>> {
  with_profile_uid?: boolean
  query?: SecurityQueryUserUserQueryContainer
  from?: <<integer>>
  sort?: <<Sort>>
  size?: <<integer>>
  search_after?: <<SortResults>>
}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
interface SecurityQueryUserResponse {
  total: <<integer>>
  count: <<integer>>
  users: SecurityQueryUserQueryUser[]
}

----


[discrete]
[[client.security.samlAuthenticate]]
== `client.security.samlAuthenticate()`

Authenticate SAML. Submits a SAML response message to Elasticsearch for consumption.

{ref}/security-api-saml-authenticate.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecuritySamlAuthenticateRequest, options?: TransportRequestOptions) => Promise<SecuritySamlAuthenticateResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecuritySamlAuthenticateRequest extends <<RequestBase>> {
  content: string
  ids: <<Ids>>
  realm?: string
}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
interface SecuritySamlAuthenticateResponse {
  access_token: string
  username: string
  expires_in: <<integer>>
  refresh_token: string
  realm: string
}

----


[discrete]
[[client.security.samlCompleteLogout]]
== `client.security.samlCompleteLogout()`

Logout of SAML completely. Verifies the logout response sent from the SAML IdP.

{ref}/security-api-saml-complete-logout.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecuritySamlCompleteLogoutRequest, options?: TransportRequestOptions) => Promise<SecuritySamlCompleteLogoutResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecuritySamlCompleteLogoutRequest extends <<RequestBase>> {
  realm: string
  ids: <<Ids>>
  query_string?: string
  content?: string
}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
type SecuritySamlCompleteLogoutResponse = boolean

----


[discrete]
[[client.security.samlInvalidate]]
== `client.security.samlInvalidate()`

Invalidate SAML. Submits a SAML LogoutRequest message to Elasticsearch for consumption.

{ref}/security-api-saml-invalidate.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecuritySamlInvalidateRequest, options?: TransportRequestOptions) => Promise<SecuritySamlInvalidateResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecuritySamlInvalidateRequest extends <<RequestBase>> {
  acs?: string
  query_string: string
  realm?: string
}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
interface SecuritySamlInvalidateResponse {
  invalidated: <<integer>>
  realm: string
  redirect: string
}

----


[discrete]
[[client.security.samlLogout]]
== `client.security.samlLogout()`

Logout of SAML. Submits a request to invalidate an access token and refresh token.

{ref}/security-api-saml-logout.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecuritySamlLogoutRequest, options?: TransportRequestOptions) => Promise<SecuritySamlLogoutResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecuritySamlLogoutRequest extends <<RequestBase>> {
  token: string
  refresh_token?: string
}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
interface SecuritySamlLogoutResponse {
  redirect: string
}

----


[discrete]
[[client.security.samlPrepareAuthentication]]
== `client.security.samlPrepareAuthentication()`

Prepare SAML authentication. Creates a SAML authentication request (`<AuthnRequest>`) as a URL string, based on the configuration of the respective SAML realm in Elasticsearch.

{ref}/security-api-saml-prepare-authentication.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecuritySamlPrepareAuthenticationRequest, options?: TransportRequestOptions) => Promise<SecuritySamlPrepareAuthenticationResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecuritySamlPrepareAuthenticationRequest extends <<RequestBase>> {
  acs?: string
  realm?: string
  relay_state?: string
}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
interface SecuritySamlPrepareAuthenticationResponse {
  id: <<Id>>
  realm: string
  redirect: string
}

----


[discrete]
[[client.security.samlServiceProviderMetadata]]
== `client.security.samlServiceProviderMetadata()`

Create SAML service provider metadata. Generate SAML metadata for a SAML 2.0 Service Provider.

{ref}/security-api-saml-sp-metadata.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecuritySamlServiceProviderMetadataRequest, options?: TransportRequestOptions) => Promise<SecuritySamlServiceProviderMetadataResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecuritySamlServiceProviderMetadataRequest extends <<RequestBase>> {
  realm_name: <<Name>>
}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
interface SecuritySamlServiceProviderMetadataResponse {
  metadata: string
}

----


[discrete]
[[client.security.suggestUserProfiles]]
== `client.security.suggestUserProfiles()`

Suggest a user profile. Get suggestions for user profiles that match specified search criteria.

{ref}/security-api-suggest-user-profile.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecuritySuggestUserProfilesRequest, options?: TransportRequestOptions) => Promise<SecuritySuggestUserProfilesResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecuritySuggestUserProfilesRequest extends <<RequestBase>> {
  name?: string
  size?: <<long>>
  data?: string | string[]
  hint?: SecuritySuggestUserProfilesHint
}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
interface SecuritySuggestUserProfilesResponse {
  total: SecuritySuggestUserProfilesTotalUserProfiles
  took: <<long>>
  profiles: <<SecurityUserProfile>>[]
}

----


[discrete]
[[client.security.updateApiKey]]
== `client.security.updateApiKey()`

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.

{ref}/security-api-update-api-key.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityUpdateApiKeyRequest, options?: TransportRequestOptions) => Promise<SecurityUpdateApiKeyResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecurityUpdateApiKeyRequest extends <<RequestBase>> {
  id: <<Id>>
  role_descriptors?: Record<string, <<SecurityRoleDescriptor>>>
  metadata?: <<Metadata>>
  expiration?: <<Duration>>
}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
interface SecurityUpdateApiKeyResponse {
  updated: boolean
}

----


[discrete]
[[client.security.updateCrossClusterApiKey]]
== `client.security.updateCrossClusterApiKey()`

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.

{ref}/security-api-update-cross-cluster-api-key.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityUpdateCrossClusterApiKeyRequest, options?: TransportRequestOptions) => Promise<SecurityUpdateCrossClusterApiKeyResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecurityUpdateCrossClusterApiKeyRequest extends <<RequestBase>> {
  id: <<Id>>
  access: <<SecurityAccess>>
  expiration?: <<Duration>>
  metadata?: <<Metadata>>
}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
interface SecurityUpdateCrossClusterApiKeyResponse {
  updated: boolean
}

----


[discrete]
[[client.security.updateSettings]]
== `client.security.updateSettings()`

Update settings for the security system index

{ref}/security-api-update-settings.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityUpdateSettingsRequest, options?: TransportRequestOptions) => Promise<SecurityUpdateSettingsResponse>
----

[discrete]
[[client.security.updateUserProfileData]]
== `client.security.updateUserProfileData()`

Update user profile data. Update specific data for the user profile that is associated with a unique ID.

{ref}/security-api-update-user-profile-data.html[{es} documentation]
[discrete]
=== Function signature

[source,ts]
----
(request: SecurityUpdateUserProfileDataRequest, options?: TransportRequestOptions) => Promise<SecurityUpdateUserProfileDataResponse>
----

[discrete]
=== Request

[source,ts,subs=+macros]
----
interface SecurityUpdateUserProfileDataRequest extends <<RequestBase>> {
  uid: <<SecurityUserProfileId>>
  if_seq_no?: <<SequenceNumber>>
  if_primary_term?: <<long>>
  refresh?: <<Refresh>>
  labels?: Record<string, any>
  data?: Record<string, any>
}

----


[discrete]
=== Response

[source,ts,subs=+macros]
----
type SecurityUpdateUserProfileDataResponse = <<AcknowledgedResponseBase>>

----