API Key management - Tablestore - Alibaba Cloud Documentation Center

Tablestore allows you to access the knowledge storage service and memory storage service by using an API Key or an AccessKey. API Keys do not require you to manage AccessKey pairs and support independent creation and revocation, making them suitable for quick integration of AI applications. This topic describes how to create and use an API Key.

Choose an authentication method

Choose an authentication method based on the resources that your application needs to access.

Authentication method	Applicable scenario	Supported scope	Usage notes
API Key	The application only calls APIs of the knowledge storage service and memory storage service.	All APIs of the knowledge storage service and memory storage service.	Easy to integrate. HTTPS is required. Access to OSS or other Tablestore APIs is not supported.
AccessKey (AK/SK)	The application also needs to access OSS or other Tablestore capabilities, or requires fine-grained permission control through RAM policies.	Determined by the permissions granted to the RAM identity.	In production environments, we recommend that you use the AccessKey of a RAM user or STS temporary credentials instead of the AccessKey of an Alibaba Cloud account.

If you only call knowledge storage and memory storage APIs, we recommend using an API Key. If you need to upload local files to OSS and then import them into a knowledge base, or access other Tablestore APIs, use an AccessKey or STS temporary credentials. For information about how to create, authorize, and configure RAM policies for an AccessKey, see Configure access permissions.

Create an API Key

Log on to the Tablestore console.
In the left-side navigation pane, click API Key.
On the API Key management page, click Create API Key.
In the Create API Key dialog box, set Expiration time.
Click Create.

Important

Keep the key value secure. It is displayed only once at creation time and cannot be retrieved again.

Use an API Key

You can use an API Key to access the knowledge storage service and memory storage service through the SDK or curl. An API Key supports all API operations of both services, including create, query, retrieve, and delete operations.

Note

When you access the services with an API Key, you must use an HTTPS endpoint.

Python

Install the AgentStorage Python SDK: pip install tablestore-agent-storage

from tablestore_agent_storage import AgentStorageClient

# Initialize the client with an API Key
client = AgentStorageClient(
    api_key="your-api-key",
    ots_endpoint="https://your-instance.cn-beijing.ots.aliyuncs.com",
    ots_instance_name="your-instance-name",
)

# Create a knowledge base
client.create_knowledge_base({"knowledgeBaseName": "product_docs"})

# List existing knowledge bases
response = client.list_knowledge_base()
for kb in response["data"]["knowledgeBases"]:
    print(kb["knowledgeBaseName"])

# Retrieve from a knowledge base
results = client.retrieve({
    "knowledgeBaseName": "product_docs",
    "retrievalQuery": {"type": "TEXT", "text": "your query"}
})
for item in results["data"]["retrievalResults"]:
    print(item["content"])

TypeScript

Install the AgentStorage TypeScript SDK: npm install @tablestore/agent-storage/

import { AgentStorageClient } from '@tablestore/agent-storage';

// Initialize the client with an API Key
const client = new AgentStorageClient({
  apiKey: 'your-api-key',
  endpoint: 'https://your-instance.cn-beijing.ots.aliyuncs.com',
  instanceName: 'your-instance-name',
});

// Create a knowledge base
await client.createKnowledgeBase({ knowledgeBaseName: 'product_docs' });

// List existing knowledge bases
const response = await client.listKnowledgeBase({});
for (const kb of response.data.knowledgeBases) {
  console.log(kb.knowledgeBaseName);
}

// Retrieve from a knowledge base
const results = await client.retrieve({
  knowledgeBaseName: 'product_docs',
  retrievalQuery: { type: 'TEXT', text: 'your query' },
});
for (const item of results.data.retrievalResults) {
  console.log(item.content);
}

curl

When you access the service directly through HTTP requests, add the x-ots-apikey and x-ots-instancename fields to the request headers.

curl -X POST 'https://your-instance.cn-beijing.ots.aliyuncs.com/CreateKnowledgeBase' \
  -H 'x-ots-instancename: your-instance-name' \
  -H 'x-ots-apikey: your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{"knowledgeBaseName": "product_docs"}'

The following example shows how to use curl to list existing knowledge bases.

curl -X POST 'https://your-instance.cn-beijing.ots.aliyuncs.com/ListKnowledgeBase' \
  -H 'x-ots-instancename: your-instance-name' \
  -H 'x-ots-apikey: your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{}'

Limits

An API Key can only access the APIs of the knowledge storage service and memory storage service. To access other Tablestore APIs, use AccessKey authentication.
When you create an API Key, the system automatically creates a dedicated RAM user and attaches the AliyunOTSFullAccess policy to the user. The permissions of the API Key are equivalent to those of the RAM user. To adjust the permissions, go to the RAM console and modify the policy of the corresponding user.
When you access the knowledge storage service and memory storage service with an API Key, the system checks both the API operation permission and the ots:CallWithBearerToken permission. If the corresponding RAM user lacks either permission, the request is rejected.