---
name: "Search::Elasticsearch::Client::7_0::Direct::Security"
section: "3pm"
platform: "linux"
package: "libsearch-elasticsearch-perl"
version: "7.30-1"
release: "Debian 11 (Bullseye)"
platforms: ["linux"]
url: "https://new.carta.tech/Search::Elasticsearch::Client::7_0::Direct::Security"
---

# Search::Elasticsearch::Client::7\_0::Direct::Security(3pm)

Plugin providing Security API for Search::Elasticsearch 7.x

## NAME

Search::Elasticsearch::Client::7\_0::Direct::Security - Plugin providing Security API for Search::Elasticsearch 7.x

## VERSION

version 7.30

## SYNOPSIS

```
    my $response = $es->security->authenticate();
```

### DESCRIPTION

This class extends the Search::Elasticsearch client with a `"security"` namespace, to support the Security APIs \<https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api.html\>.

The full documentation for the Security feature is available here: \<https://www.elastic.co/guide/en/x-pack/current/xpack-security.html\>

## GENERAL METHODS

### "authenticate()"

```
    $response = $es->security->authenticate()
```

The `"authenticate()"` method checks that the `"userinfo"` is correct and returns a list of which roles are assigned to the user.

See the authenticate docs \<https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-authenticate.html\> for more information.

Query string parameters:\
     `"error_trace"`,\
     `"human"`

### "clear\_cached\_realms()"

```
    $response = $es->security->clear_cached_realms(
        realms => $realms       # required  (comma-separated string)
    );
```

The `"clear_cached_realms()"` method clears the caches for the specified realms

Query string parameters:\
     `"error_trace"`,\
     `"human"`,\
     `"usernames"`

See the clear\_cached\_realms docs \<https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-clear-cache.html\> for more information.

## USER METHODS

### "put\_user()"

```
    $response = $es->security->put_user(
        username => $username,     # required
        body     => {...}          # required
    );
```

The `"put_user()"` method creates a new user or updates an existing user.

See the User Management docs \<https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-users.html\> for more information.

Query string parameters:\
     `"error_trace"`,\
     `"human"`

### "get\_user()"

```
    $response = $es->security->get_user(
        username => $username | \@usernames     # optional
    );
```

The `"get_user()"` method retrieves info for the specified users (or all users).

See the User Management docs \<https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-users.html\> for more information.

Query string parameters:\
     `"error_trace"`,\
     `"human"`

### "delete\_user()"

```
    $response = $es->security->delete_user(
        username => $username       # required
    );
```

The `"delete_user()"` method deletes the specified user.

See the User Management docs \<https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-users.html\> for more information.

Query string parameters:\
     `"error_trace"`,\
     `"human"`

### "change\_password()"

```
    $response = $es->security->change_password(
        username => $username       # optional
        body => {
            password => $password   # required
        }
    )
```

The `"change_password()"` method changes the password for the specified user.

See the User Management docs \<https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-users.html\> for more information.

### "disable\_user()"

```
    $response = $es->security->disable_user(
        username => $username       # required
    );
```

The `"disable_user()"` method disables the specified user.

See the User Management docs \<https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-users.html\> for more information.

Query string parameters:\
     `"error_trace"`,\
     `"human"`

### "enable\_user()"

```
    $response = $es->security->enable_user(
        username => $username       # required
    );
```

The `"enable_user()"` method enables the specified user.

See the User Management docs \<https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-users.html\> for more information.

Query string parameters:\
     `"error_trace"`,\
     `"human"`

## ROLE METHODS

### "put\_role()"

```
    $response = $es->security->put_role(
        name => $name,             # required
        body     => {...}          # required
    );
```

The `"put_role()"` method creates a new role or updates an existing role.

See the Role Management docs \<https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-roles.html\> for more information.

Query string parameters:\
     `"error_trace"`,\
     `"human"`

### "get\_role()"

```
    $response = $es->security->get_role(
        name => $name | \@names     # optional
    );
```

The `"get_role()"` method retrieves info for the specified roles (or all roles).

See the Role Management docs \<https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-roles.html\> for more information.

Query string parameters:\
     `"error_trace"`,\
     `"human"`

### "delete\_role()"

```
    $response = $es->security->delete_role(
        name => $name       # required
    );
```

The `"delete_role()"` method deletes the specified role.

See the Role Management docs \<https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-roles.html\> for more information.

Query string parameters:\
     `"error_trace"`,\
     `"human"`

### "clear\_cached\_roles()"

```
    $response = $es->security->clear_cached_roles(
        names => $names       # required  (comma-separated string)
    );
```

The `"clear_cached_roles()"` method clears the caches for the specified roles.

See the Role Management docs \<https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-roles.html\> for more information.

Query string parameters:\
     `"error_trace"`,\
     `"human"`

## ROLE MAPPING METHODS

### "put\_role\_mapping()"

```
    $response = $es->security->put_role_mapping(
        name => $name,             # required
        body     => {...}          # required
    );
```

The `"put_role_mapping()"` method creates a new role mapping or updates an existing role mapping.

See the Role Mapping docs \<https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-role-mapping.html\> for more information.

Query string parameters:\
     `"error_trace"`,\
     `"human"`

### "get\_role\_mapping()"

```
    $response = $es->security->get_role_mapping(
        name => $name,             # optional
    );
```

The `"get_role_mapping()"` method retrieves one or more role mappings.

See the Role Mapping docs \<https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-role-mapping.html\> for more information.

Query string parameters:\
     `"error_trace"`,\
     `"human"`

### "delete\_role\_mapping()"

```
    $response = $es->security->delete_role_mapping(
        name => $name,             # required
    );
```

The `"delete_role_mapping()"` method deletes a role mapping.

See the Role Mapping docs \<https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-role-mapping.html\> for more information.

Query string parameters:\
     `"error_trace"`,\
     `"human"`

## TOKEN METHODS

### "get\_token()"

```
    $response = $es->security->get_token(
        body     => {...}          # required
    );
```

The `"get_token()"` method enables you to create bearer tokens for access without requiring basic authentication.

See the Token Management docs \<https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-tokens.html\> for more information.

Query string parameters:\
     `"error_trace"`,\
     `"human"`

### "invalidate\_token()"

```
    $response = $es->security->invalidate_token(
        body     => {...}          # required
    );
```

The `"invalidate_token()"` method enables you to invalidate bearer tokens for access without requiring basic authentication.

See the Token Management docs \<https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-tokens.html\> for more information.

Query string parameters:\
     `"error_trace"`,\
     `"human"`

## API KEY METHODS

### "create\_api\_key()"

```
    $response = $es->security->create_api_key(
        body    => {...}            # required
    )
```

The `"create_api_key()"` API is used to create API keys which can be used for access instead of basic authentication.

Query string parameters:\
     `"error_trace"`,\
     `"filter_path"`,\
     `"human"`,\
     `"refresh"`

See the Create API Key docs \<https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-api-key.html\> for more.

### "get\_api\_key()"

```
    $response = $es->security->get_api_key(
        id          => $id,         # optional
        name        => $name,       # optional
        realm_name  => $realm,      # optional
        username    => $username    # optional
    )
```

The `"get_api_key()"` API is used to get information about an API key.

Query string parameters:\
     `"error_trace"`,\
     `"filter_path"`,\
     `"human"`,\
     `"id"`,\
     `"name"`,\
     `"realm_name"`,\
     `"username"`

See the Get API Key docs \<https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-get-api-key.html\> for more.

### "invalidate\_api\_key()"

```
    $response = $es->security->invalidate_api_key(
        id          => $id,         # optional
        name        => $name,       # optional
        realm_name  => $realm,      # optional
        username    => $username    # optional
    )
```

The `"invalidate_api_key()"` API is used to invalidate an API key.

Query string parameters:\
     `"error_trace"`,\
     `"filter_path"`,\
     `"human"`,\
     `"id"`,\
     `"name"`,\
     `"realm_name"`,\
     `"username"`

See the Invalidate API Key docs \<https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-invalidate-api-key.html\> for more.

## USER PRIVILEGE METHODS

### "get\_user\_privileges()"

```
    $response = $es->get_user_privileges();
 The C<get_user_privileges()> method retrieves the privileges granted to the current user.
 Query string parameters:
    C<error_trace>,
    C<filter_path>,
    C<human>
```

### "has\_privileges()" $response = $es-\>has\_privileges( user =\> $user, # optional body =\> {...} # required );

```
 The C<has_privileges()> method checks whether the current or specified user has the listed privileges.
 Query string parameters:
    C<error_trace>,
    C<filter_path>,
    C<human>
```

See the Has Privileges docs \<https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-has-privileges.html\> for more.

## APPLICATION PRIVILEGE METHODS

### "put\_privileges()"

```
    $response = $es->put_privileges(
        application     => $application,    # required
        name            => $name,           # required
        body            => {...}            # required
    );
 The C<put_privileges()> method creates or updates the named privilege for a particular application.
 Query string parameters:
    C<error_trace>,
    C<filter_path>,
    C<human>,
    C<refresh>
```

See the Create or Update Application Privileges docs \<https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-put-privileges.html\> for more.

### "get\_privileges()"

```
    $response = $es->get_privileges(
        application     => $application,    # required
        name            => $name,           # required
    );
 The C<get_privileges()> method retrieves the named privilege for a particular application.
 Query string parameters:
    C<error_trace>,
    C<filter_path>,
    C<human>
```

See the Get Application Privileges docs \<https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-get-privileges.html\> for more.

### "delete\_privileges()"

```
    $response = $es->delete_privileges(
        application     => $application,    # required
        name            => $name,           # required
    );
 The C<delete_privileges()> method deletes the named privilege for a particular application.
 Query string parameters:
    C<error_trace>,
    C<filter_path>,
    C<human>,
    C<refresh>
```

See the Delete Application Privileges docs \<https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-delete-privilege.html\> for more.

## AUTHOR

Enrico Zimuel \<enrico.zimuel@elastic.co\>

## COPYRIGHT AND LICENSE

This software is Copyright (c) 2020 by Elasticsearch BV.

This is free software, licensed under:

```
  The Apache License, Version 2.0, January 2004
```