# Create or update roles


**POST /_security/role/{name}**

**All methods and paths for this operation:**

<div>
                      <span class="operation-verb put">PUT</span>
                      <span class="operation-path">/_security/role/{name}</span>
                      </div>
                    <div>
                      <span class="operation-verb post">POST</span>
                      <span class="operation-path">/_security/role/{name}</span>
                      </div>
                    

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.

## Required authorization

* Cluster privileges: `manage_security`


[External documentation](https://www.elastic.co/guide/en/elasticsearch/reference/8.19/defining-roles.html)

## Servers
- http://api.example.com: http://api.example.com ()


## Authentication methods
- Api key auth
- Basic auth
- Bearer auth


## Parameters

### Path parameters
- **name** (string)
  The name of the role.

### Query parameters
- **refresh** (string)
  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: application/json (object)

- **applications** (array[object])
  A list of application privilege entries.
- **cluster** (array[string])
  A list of cluster privileges. These privileges define the cluster-level actions for users with this role.
- **global** (object)
  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** (array[object])
  A list of indices permissions entries.
- **remote_indices** (array[object])
  A list of remote indices permissions entries.

  NOTE: Remote indices are effective for remote clusters configured with the API key based model.
  They have no effect for remote clusters configured with the certificate based model.
- **remote_cluster** (array[object])
  A list of remote cluster permissions entries.
- **metadata** (object)
  Optional metadata. Within the metadata object, keys that begin with an underscore (`_`) are reserved for system use.
- **run_as** (array[string])
  A list of users that the owners of this role can impersonate. *Note*: in Serverless, the run-as feature is disabled. For API compatibility, you can still specify an empty `run_as` field, but a non-empty list will be rejected.
- **description** (string)
  Optional description of the role descriptor
- **transient_metadata** (object)
  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.


## Responses
### 200


#### Body: application/json (object)
- **role** (object)
  When an existing role is updated, `created` is set to `false`.


[Powered by Bump.sh](https://bump.sh)