You're viewing version 3.8 of the OpenSearch documentation. This version is no longer maintained. For the latest version, see the current documentation. For information about OpenSearch version maintenance, see Release Schedule and Maintenance Policy.
Create API Key API
Introduced 3.7
Creates a new API key with the specified permissions and duration.
Endpoints
POST /_plugins/_security/api/apitokens
Request body fields
The request body is required. It is a JSON object with the following fields.
| Field | Data type | Description | Required |
|---|---|---|---|
name | String | A unique name for the key. Must match the pattern [a-zA-Z0-9_-]+. | Yes |
cluster_permissions | Array of strings | The cluster-level permissions or action groups granted to the key. Default is an empty array. | No |
index_permissions | Array of objects | The index-level permissions granted to the key. Default is an empty array. | No |
duration_seconds | Long | The length of time for which the key is valid, in seconds. The maximum is set by max_duration_seconds, which defaults to 7,776,000 (90 days). If omitted, the key is valid for max_duration_seconds. | No |
The index_permissions objects contain the following fields.
| Field | Data type | Description | Required |
|---|---|---|---|
index_pattern | Array of strings | The indexes to which the permissions apply. Supports wildcard patterns, such as logs-*. | Yes |
allowed_actions | Array of strings | The actions or action groups permitted on the matching indexes. | Yes |
Example request
POST _plugins/_security/api/apitokens
{
"name": "test-token",
"duration_seconds": 86400,
"cluster_permissions": [
"cluster_monitor"
],
"index_permissions": [
{
"index_pattern": [
"logs*"
],
"allowed_actions": [
"read"
]
}
]
}
Example response
{
"id": "_ofOi6ABkhwU_cGa4M3v",
"token": "os_7EoHbn6PVeBwnqFGFDT0g-NBSI46Nq5PutcHHsmCFHg"
}
The token value is returned only once and cannot be retrieved again. Store it securely.
Response body fields
The response body is a JSON object with the following fields.
| Field | Data type | Description |
|---|---|---|
id | String | The unique identifier for the key (used for revocation). |
token | String | The plain-text token to use in the Authorization: ApiKey <token> header. |