How to Authenticate with the MemoryCore API: Header-Based Security Guide

Every request to the MemoryCore API must include an Authorization: Bearer <TOKEN> header and an x-tdai-service-id header, which the HTTP gateway validates against the configured TDAI_GATEWAY_API_KEY environment variable or YAML configuration.

The TencentDB Agent Memory repository implements a gateway-based authentication layer for its MemoryCore service. As defined in MemoryCore/README.md, the system requires a pre-shared secret token to access all v3 endpoints, with the gateway rejecting unauthorized requests with a 401 status code.

Authentication Requirements

MemoryCore's HTTP gateway intercepts all incoming requests to enforce token validation. According to the source configuration in MemoryCore/tdai-gateway.standalone.yaml, two specific headers must accompany every API call:

• Authorization: Must follow the format Bearer <TOKEN>, where <TOKEN> matches the gateway's configured API key.
• x-tdai-service-id: Identifies the specific Memory instance (e.g., default) targeted by the request.

The gateway permits unauthenticated access only to the /health endpoint and CORS pre-flight requests. All other endpoints, including conversation management and atomic memory operations, return 401 Unauthorized if either header is missing or the token is invalid.

Configuring the Gateway Token

Before client authentication can succeed, you must configure the gateway's validation token.

Environment Variable Method

Set the TDAI_GATEWAY_API_KEY environment variable to a cryptographically secure random string before starting the gateway service. This variable is referenced by the gateway configuration to validate incoming bearer tokens.

Configuration File Method

Alternatively, specify the token directly in MemoryCore/tdai-gateway.standalone.yaml. The gateway loads this configuration during initialization and uses it to verify the Authorization header on subsequent requests.

Implementing Authentication in Client Code

Once the gateway token is configured, include the required headers in every API request.

cURL Implementation

For command-line testing or shell scripts, export the token and include both headers in your HTTP requests:

export TDAI_GATEWAY_API_KEY="replace-with-a-strong-random-token"

curl -X GET http://127.0.0.1:8420/v3/conversation \
  -H "Authorization: Bearer $TDAI_GATEWAY_API_KEY" \
  -H "x-tdai-service-id: default"

TypeScript SDK Implementation

The official TypeScript SDK handles header injection automatically through the MemoryClient class defined in sdk/memory-core/typescript/src/v3/client.ts. Initialize the client with your gateway token and service ID:

import { MemoryClient } from '../sdk/memory-core/typescript/src/v3/client.js';

const client = new MemoryClient({
  baseUrl: 'http://127.0.0.1:8420',
  apiKey: process.env.TDAI_GATEWAY_API_KEY,
  serviceId: 'default'
});

// Create a conversation with authenticated request
const resp = await client.post('/v3/conversation', {
  team_id: 'team1',
  agent_id: 'agentA',
  user_id: 'user123',
  title: 'Demo conversation'
});

Python SDK Implementation

The Python SDK, documented in sdk/memory-core/python/README.md, provides equivalent functionality:

from memory_core import MemoryClient

client = MemoryClient(
    base_url="http://127.0.0.1:8420",
    api_key="replace-with-a-strong-random-token",
    service_id="default"
)

resp = client.get("/v3/atomic")
print(resp.json())

Per-User Authentication Layer

For deployments requiring user-level access control beyond the gateway token, combine the base authentication with the x-tdai-user-id header. This header is typically populated by the /v3/meta/auth/verify endpoint after validating end-user credentials, allowing the MemoryCore service to distinguish between different users while maintaining the gateway-level security layer.

Summary

• Header requirements: Every API request must include Authorization: Bearer <TOKEN> and x-tdai-service-id: <INSTANCE>.
• Token source: The gateway validates tokens against TDAI_GATEWAY_API_KEY defined in environment variables or tdai-gateway.standalone.yaml.
• SDK support: Official TypeScript and Python clients in sdk/memory-core/ automatically inject required headers when initialized with apiKey and serviceId parameters.
• Exclusions: Only the /health endpoint and CORS pre-flight requests bypass authentication.

Frequently Asked Questions

What happens if I omit the authentication headers?

The MemoryCore gateway returns a 401 Unauthorized status code for any request missing the Authorization or x-tdai-service-id headers, or when the bearer token does not match the configured TDAI_GATEWAY_API_KEY. This applies to all v3 endpoints except the health check.

Is the gateway token the same as a user password?

No. The TDAI_GATEWAY_API_KEY is a service-level secret that authorizes any client holding it to access the MemoryCore API. It is not a user credential. For per-user authentication, implement the x-tdai-user-id header populated through the /v3/meta/auth/verify workflow.

Which source files define the authentication behavior?

The authentication logic is configured in MemoryCore/tdai-gateway.standalone.yaml and documented in MemoryCore/README.md. Client implementations reside in sdk/memory-core/typescript/src/v3/client.ts for TypeScript and sdk/memory-core/python/ for Python.

Can I use the MemoryCore API without authentication during development?

Only the /health endpoint is accessible without authentication. All functional endpoints require valid headers even in local development environments to simulate production security conditions.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}