# opensearch-security

Part of **OPENSEARCH**

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

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

# OpenSearch Security and Access Control

## Capabilities Overview

| Sub-capability | Calling Mode | Description |
|----------------|--------------|-------------|
| Authenticate API Requests | Synchronous | Implement authentication mechanisms for secure API access. |
| Create OpenSearch Client with STS Token | Synchronous | Initialize an OpenSearch client using temporary security tokens. |

## API Calling Patterns

### Authentication
The primary authentication method is **Bearer Token** via the `Authorization` header.

- Use the header: `Authorization: Bearer YOUR_API_KEY`
- Store your API key in the environment variable: `DASHSCOPE_API_KEY`
- While other methods (e.g., AccessKey/Secret) may be supported in specific SDK contexts, the Bearer Token approach is recommended for general REST API calls.

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

```text
http://opensearch-{region}.aliyuncs.com
```

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

For generic status or metadata APIs (e.g., `/api/v1/status`), a custom domain may be used (e.g., `https://your-es-endpoint.com`), but production services should use the official Alibaba Cloud regional endpoints.

### Synchronous API Calls
All documented operations in this domain are synchronous:

1. Construct a request with the correct `Authorization` header.
2. Send the request to the appropriate regional endpoint.
3. Receive an immediate JSON response (success or error).
4. Handle HTTP status codes (e.g., 401, 403) as needed.

No polling or streaming is involved—each request completes in one round trip.

## Parameter Reference

### Authenticate API Requests

| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|----------|---------|-------------|-------------|
| Authorization | string | Yes | — | Must start with `Bearer ` | The authorization header containing the API key or bearer token. |

### Create OpenSearch Client with STS Token

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

## Code Examples

### Authenticate API Request - curl - all

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

### Authenticate API Request - 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())
```

### Create 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 that the `Authorization` header is correctly formatted and that the API key is valid and active. |
| 403 | Forbidden. The API key does not have sufficient permissions to perform the requested operation. | Check the assigned roles and permissions for the API key or RAM user; ensure it has the required OpenSearch actions allowed. |
| InvalidAccessKeyId | The provided AccessKey ID is invalid or does not exist. | Confirm that the temporary AccessKey ID was correctly retrieved from the STS AssumeRole response. |
| InvalidSecurityToken | The provided STS token is invalid, expired, or has been revoked. | Refresh the STS token by re-calling AssumeRole; tokens typically expire after 15 minutes to several hours. |
| Unauthorized | The request is not authorized due to insufficient permissions. | Ensure the RAM role assumed via STS has the necessary OpenSearch permissions attached. |

## Environment Requirements

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

## FAQ

Q: Can I use permanent AccessKey pairs instead of STS tokens?
A: Yes, but STS tokens are strongly recommended for enhanced security, especially in serverless or multi-tenant environments, as they provide short-lived, scoped credentials.

Q: What permissions are required to call OpenSearch APIs?
A: The RAM user or role must have policies granting actions like `opensearch:DescribeInstance`, `opensearch:UpdateInstance`, or other relevant OpenSearch API permissions depending on the operation.

Q: Why am I getting a 403 error even with a valid API key?
A: Your API key (or underlying RAM user/role) likely lacks the specific permissions needed for the requested resource or action. Review the attached policies in the RAM console.

Q: How do I obtain an STS token?
A: Call the `AssumeRole` API from Alibaba Cloud STS service using a trusted RAM user. The response includes `AccessKeyId`, `AccessKeySecret`, and `SecurityToken`.

Q: Is the Bearer Token method compatible with all OpenSearch SDKs?
A: The Bearer Token is used for direct REST API calls. SDKs (like the Java OpenSearch SDK) typically use AccessKey/Secret + SecurityToken for authentication, as shown in the STS example.

## 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.