Create or update application privileges

POST also PUT /_security/privilege

Auth

To use this API, you must have one of the following privileges:

The manage_security cluster privilege (or a greater privilege such as all).
The "Manage Application Privileges" global privilege for the application being referenced in the request.

Application names are formed from a prefix, with an optional suffix that conform to the following rules:

The prefix must begin with a lowercase ASCII letter.
The prefix must contain only ASCII letters or digits.
The prefix must be at least 3 characters long.
If the suffix exists, it must begin with either a dash - or _.
The suffix cannot contain any of the following characters: \, /, *, ?, ", <, >, |, ,, *.
No part of the name can contain whitespace.

Privilege names must begin with a lowercase ASCII letter and must contain only ASCII letters and digits along with the characters _, -, and ..

Action names can contain any number of printable ASCII characters and must contain at least one of the following characters: /, *, :.

Read the reference documentation

Required privileges

Cluster privileges manage_security

Query parameters

refresh enum: 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.; Values: true false wait_for

Request body

Type: map string to string to object

Response

application/json

Response Type: map string to string to object

View as Markdown

Examples

Request Console 1 / 8 languages

Run POST /_security/privilege to add a single application privilege. The wildcard (*) means that this privilege grants access to all actions that start with data:read/. Elasticsearch does not assign any meaning to these actions. However, if the request includes an application privilege such as data:read/users or data:read/settings, the has privileges API respects the use of a wildcard and returns true.

Console Kibana Dev Tools

POST /_security/privilege
{
  "myapp": {
    "read": {
      "actions": [ 
        "data:read/*" , 
        "action:login" ],
        "metadata": { 
          "description": "Read access to myapp"
        }
      }
    }
}

JavaScript Elasticsearch JavaScript Client

const response = await client.security.putPrivileges({
  privileges: {
    myapp: {
      read: {
        actions: ["data:read/*", "action:login"],
        metadata: {
          description: "Read access to myapp",
        },
      },
    },
  },
});

Python Elasticsearch Python Client

resp = client.security.put_privileges(
    privileges={
        "myapp": {
            "read": {
                "actions": [
                    "data:read/*",
                    "action:login"
                ],
                "metadata": {
                    "description": "Read access to myapp"
                }
            }
        }
    },
)

curl Shell

curl -X POST "$ELASTICSEARCH_URL/_security/privilege" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "myapp": {
      "read": {
        "actions": [
          "data:read/*",
          "action:login"
        ],
        "metadata": {
          "description": "Read access to myapp"
        }
      }
    }
  }'

Java Elasticsearch Java Client

client.security().putPrivileges(p -> p
    .privileges("myapp", "read", pr -> pr
        .actions(List.of("data:read/*","action:login"))
        .metadata("description", JsonData.fromJson("\"Read access to myapp\""))
    )
);

C# Elasticsearch .NET Client

var response = await client.Security
    .PutPrivilegesAsync(d1 => d1
        .Privileges(new Dictionary<string, IDictionary<string,PrivilegeActions>>()
        {
            { "myapp", new Dictionary<string, PrivilegeActions>()
            {
                { "read", new()
                {
                    Actions = ["data:read/*", "action:login"],
                    Metadata = new Dictionary<string, object>()
                    {
                        { "description", "Read access to myapp" }
                    }
                } }
            } }
        })
    );

PHP Elasticsearch PHP Client

$resp = $client->security()->putPrivileges([
    "body" => [
        "myapp" => [
            "read" => [
                "actions" => array(
                    "data:read/*",
                    "action:login",
                ),
                "metadata" => [
                    "description" => "Read access to myapp",
                ],
            ],
        ],
    ],
]);

Ruby Elasticsearch Ruby Client

response = client.security.put_privileges(
  body: {
    "myapp": {
      "read": {
        "actions": [
          "data:read/*",
          "action:login"
        ],
        "metadata": {
          "description": "Read access to myapp"
        }
      }
    }
  }
)

Response

A successful response from PUT /_security/privilege.

{
  "myapp": {
    "read": {
      "created": true 
    }
  }
}

Request Console 1 / 8 languages

Run POST /_security/privilege to add multiple application privileges.

Console Kibana Dev Tools

POST /_security/privilege
{
  "app01": {
    "read": {
      "actions": [ "action:login", "data:read/*" ]
    },
    "write": {
      "actions": [ "action:login", "data:write/*" ]
    }
  },
  "app02": {
    "all": {
      "actions": [ "*" ]
    }
  }
}

JavaScript Elasticsearch JavaScript Client

const response = await client.security.putPrivileges({
  privileges: {
    app01: {
      read: {
        actions: ["action:login", "data:read/*"],
      },
      write: {
        actions: ["action:login", "data:write/*"],
      },
    },
    app02: {
      all: {
        actions: ["*"],
      },
    },
  },
});

Python Elasticsearch Python Client

resp = client.security.put_privileges(
    privileges={
        "app01": {
            "read": {
                "actions": [
                    "action:login",
                    "data:read/*"
                ]
            },
            "write": {
                "actions": [
                    "action:login",
                    "data:write/*"
                ]
            }
        },
        "app02": {
            "all": {
                "actions": [
                    "*"
                ]
            }
        }
    },
)

curl Shell

curl -X POST "$ELASTICSEARCH_URL/_security/privilege" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "app01": {
      "read": {
        "actions": [
          "action:login",
          "data:read/*"
        ]
      },
      "write": {
        "actions": [
          "action:login",
          "data:write/*"
        ]
      }
    },
    "app02": {
      "all": {
        "actions": [
          "*"
        ]
      }
    }
  }'

Java Elasticsearch Java Client

client.security().putPrivileges(p -> p
    .privileges(Map.of("app02", "all", pr -> pr
        .actions("*"),"app01", Map.of("read", Actions.of(a -> a
            .actions(List.of("action:login","data:read/*"))),"write", Actions.of(a -> a
            .actions(List.of("action:login","data:write/*"))))))
);

C# Elasticsearch .NET Client

var response = await client.Security
    .PutPrivilegesAsync(d1 => d1
        .Privileges(new Dictionary<string, IDictionary<string,PrivilegeActions>>()
        {
            { "app01", new Dictionary<string, PrivilegeActions>()
            {
                { "read", new()
                {
                    Actions = ["action:login", "data:read/*"]
                } },
                { "write", new()
                {
                    Actions = ["action:login", "data:write/*"]
                } }
            } },
            { "app02", new Dictionary<string, PrivilegeActions>()
            {
                { "all", new()
                {
                    Actions = ["*"]
                } }
            } }
        })
    );

PHP Elasticsearch PHP Client

$resp = $client->security()->putPrivileges([
    "body" => [
        "app01" => [
            "read" => [
                "actions" => array(
                    "action:login",
                    "data:read/*",
                ),
            ],
            "write" => [
                "actions" => array(
                    "action:login",
                    "data:write/*",
                ),
            ],
        ],
        "app02" => [
            "all" => [
                "actions" => array(
                    "*",
                ),
            ],
        ],
    ],
]);

Ruby Elasticsearch Ruby Client

response = client.security.put_privileges(
  body: {
    "app01": {
      "read": {
        "actions": [
          "action:login",
          "data:read/*"
        ]
      },
      "write": {
        "actions": [
          "action:login",
          "data:write/*"
        ]
      }
    },
    "app02": {
      "all": {
        "actions": [
          "*"
        ]
      }
    }
  }
)

Response

A successful response from PUT /_security/privilege.

{
  "myapp": {
    "read": {
      "created": true 
    }
  }
}