API Reference

Authentication

Use API keys with MemorySyncClient for the customer /memory contract. Use bearer access tokens with ControlPlaneClient for protected control-plane methods; initialize that client without a token only for login. Project and end-user scope apply only where the selected operation documents them.

Authentication and operation scope

Input	Where	Contract
API key	`X-API-Key` / `api_key` / `apiKey`	Required by `MemorySyncClient` and `/memory`; it is not the control-plane credential.
Bearer access token	`Authorization: Bearer` / `access_token` / `accessToken`	Required by protected `ControlPlaneClient` methods. Login accepts credentials without an access token.
Project ID	`X-Project-ID` / `project_id` / `projectId`	Optional; selects a project when the operation supports project scope.
End-user ID	`X-End-User-ID` / `end_user_id` / `endUserId`	Required for API-key calls to user-scoped memory operations; it is not used as control-plane authentication.

Configure authentication

import os
from memorysync import MemorySyncClient

client = MemorySyncClient(
    api_key=os.environ["MEMORYSYNC_API_KEY"],
    base_url="https://api.memorysync.io",
    project_id=os.environ["MEMORYSYNC_PROJECT_ID"],
    end_user_id="usr_7f3a9c2e",
)

Authentication result paths

Authentication outcomes

2xx

Authenticated and scoped

Process the operation-specific response.

401

Authentication failed

Confirm the server loaded and sent an active API key.

403

Scope is not allowed

Confirm the key is allowed to access the selected project.

404

Resource unavailable in scope

Check the project, end-user ID, and resource ID together.

401-response.json

{"detail":"Unauthenticated"}

Protect credentials and identity

Do

Establish scope from trusted state.

Store keys in a server secret manager.
Map signed-in users to opaque identifiers.
Use the same trusted scope on later reads and writes.

Avoid

Do not transfer trust to clients.

Do not put API keys in browser or mobile bundles.
Do not use an email address as the end-user ID.
Do not accept arbitrary scope headers from an untrusted request.

Scope behavior in the SDK-backed `/memory` contract

Scope behavior	Operations	Required context for API-key callers
End-user scoped	Add, Bulk add, Get, Query, Summarize, Update, Forget, Create relation	API key plus stable opaque end-user ID; project ID when your application selects a project.
Authenticated-principal scoped	Compose, Export	API key and optional project ID. Omit the end-user header because these `/memory` operations do not use it.

Map application identity safely

Identity mapping

Authenticated user → opaque MemorySync scope

Resolve scope on your server before constructing the request.

Application session: Verified server state
Do not trust an arbitrary client-provided user identifier.
Opaque ID: usr_7f3a9c2e
Use a stable non-sensitive identifier, not an email address.
Project: Trusted workload ID
Select it from server configuration or authorized application state.
API key: Secret manager value
Never expose it in browser code, URLs, screenshots, or client logs.

Troubleshoot authentication and scope

Symptom	Likely check	Safe next action
`401`	Missing, malformed, inactive, or unavailable API key.	Verify server configuration without printing the key.
`403`	The authenticated caller cannot use the selected scope.	Check project access and operation permissions.
`404` for a known ID	The ID is not visible in the supplied scope.	Check the ID, project, and end-user identifier together.
Unexpected empty query	Write and read scope may differ.	Compare trusted project and end-user values used by both calls.