# es-security

Part of **ES**

<!-- intent-backlink:auto -->

> 💡 **Path Selection**: This skill is one implementation path for [Manage access control and security settings](../../intent/es-manage-access/SKILL.md). If you're unsure which path to take, check the routing skill first.

# Elasticsearch Security

## Capabilities Overview

| Sub-capability | Calling Mode | Description |
|----------------|--------------|-------------|
| Authenticate API Requests | Synchronous | Implement secure authentication for API calls to Elasticsearch. |
| Use STS Tokens | Synchronous | Create OpenSearch clients using temporary STS tokens for secure access. |

## API Calling Patterns

### Authentication
Use **Bearer Token** authentication as the primary method for Elasticsearch API requests.

- Include the header: `Authorization: Bearer <your_api_key>`
- Store your API key in the environment variable: `DASHSCOPE_API_KEY`
- Alternative methods like AccessKey/SecretKey signing exist but are less common for standard REST API usage; prefer Bearer tokens for simplicity and compatibility.

### Service Endpoint
Elasticsearch APIs use region-specific endpoints with the pattern:

`https://opensearch-{region}.aliyuncs.com`

Common regions include:
- `cn-hangzhou`
- `cn-shanghai`
- `cn-beijing`

For general status or metadata APIs, a generic endpoint like `https://your-es-endpoint.com/api/v1/status` may be used (replace with your actual cluster endpoint).

### Synchronous API Calls
All documented Elasticsearch Security APIs use synchronous request-response patterns:

1. Construct an HTTP request with the appropriate method (GET, POST, etc.)
2. Add the `Authorization: Bearer YOUR_API_KEY` header
3. Send the request to the correct regional endpoint
4. Process the immediate JSON response
5. Handle errors based on HTTP status codes (401, 403, etc.)

No asynchronous polling or streaming is used in the security-related APIs.

## Parameter Reference

### Authenticate API Requests

| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|----------|---------|-------------|-------------|
| Authorization | string | true | — | — | The authorization header containing the API key or bearer token. |

### Use STS Tokens

| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|----------|---------|-------------|-------------|
| accessKeyId | string | true | — | — | The temporary AccessKey ID obtained from the AssumeRole operation. |
| accessKeySecret | string | true | — | — | The temporary AccessKey secret obtained from the AssumeRole operation. |
| endpoint | string | true | — | e.g., http://opensearch-cn-hangzhou.aliyuncs.com | The endpoint URL for the OpenSearch service. |
| securityToken | string | true | — | — | The temporary STS token used to authenticate the request. |

## Code Examples

### Basic API Authentication - curl - all

```bash
curl -X GET https://your-es-endpoint.com/api/v1/status \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Basic API Authentication - Python - all

```python
import requests

headers = {
    "Authorization": "Bearer YOUR_API_KEY"
}

response = requests.get("https://your-es-endpoint.com/api/v1/status", headers=headers)
print(response.json())
```

### OpenSearch Client with STS Token - Java - china

```java
OpenSearch openSearch = new OpenSearch("<Temporary AccessKey ID>",
    "<Temporary AccessKey secret>", "http://opensearch-cn-hangzhou.aliyuncs.com");
openSearch.setSecurityToken("<Temporary STS token>");
```

## Error Handling

| Error Code | Description | Recommended Action |
|------------|-------------|---------------------|
| 401 | Unauthorized access. The provided API key or token is invalid or missing. | Verify your API key is correct and included in the Authorization header. |
| 403 | Forbidden. The API key does not have sufficient permissions to perform the requested operation. | Check RAM policies and ensure your API key has the required permissions. |
| InvalidAccessKeyId | The provided AccessKey ID is invalid or does not exist. | Confirm the temporary AccessKey ID from STS is correctly copied and not expired. |
| InvalidSecurityToken | The provided STS token is invalid, expired, or has been revoked. | Request a new STS token using AssumeRole and retry. |
| Unauthorized | The request is not authorized due to insufficient permissions. | Review the role permissions granted during the AssumeRole operation. |

## Environment Requirements

- For Java STS usage: `open-search-sdk>=1.0.0`
- Set your API key: `export DASHSCOPE_API_KEY=your_key_here`

## FAQ

Q: How do I obtain an API key for Elasticsearch?
A: API keys can be generated in the Alibaba Cloud console under your Elasticsearch service instance, typically tied to a RAM user with appropriate permissions.

Q: Can I use both API keys and STS tokens?
A: Yes. Use API keys (bearer tokens) for long-lived server applications, and STS tokens for short-term, role-based access with temporary credentials.

Q: What permissions does my API key need?
A: Your API key must be associated with a RAM user or role that has been granted specific Elasticsearch actions (e.g., `opensearch:Search`, `opensearch:Write`) via RAM policies.

Q: Why am I getting a 403 error even with a valid API key?
A: The RAM user linked to your API key likely lacks the necessary permissions. Attach a policy granting the required Elasticsearch actions to the user or role.

Q: Are STS tokens more secure than static API keys?
A: Yes. STS tokens are temporary, automatically expire, and follow the principle of least privilege, reducing the risk of credential leakage and misuse.

## Pricing & Billing

### Billing Model
API calls are billed per request.

### Price Reference

| Tier | Input Price | Output Price |
|------|-------------|--------------|
| default | 0.001 / | 0.002 / |

### Free Tier
 1000 

### Usage Limits
100 QPS

### Billing Notes
API calls are billed per request; free tier resets monthly.