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

> Authenticate with the MemoryCore API using header based security. Learn how to include Authorization and x-tdai-service-id headers for secure access to your MemoryCore API.

- Repository: [Tencent Cloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory)
- Tags: how-to-guide
- Published: 2026-08-27

---

**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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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:

```bash
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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/typescript/src/v3/client.ts). Initialize the client with your gateway token and service ID:

```typescript
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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/python/README.md), provides equivalent functionality:

```python
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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/tdai-gateway.standalone.yaml) and documented in [`MemoryCore/README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/README.md). Client implementations reside in [`sdk/memory-core/typescript/src/v3/client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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.