Authentication

Every request needs two pieces: an API key and an organization id. The API key alone is not sufficient — the auth layer keys auth records by (org_id, api_key_hash) and can’t reverse-lookup the org from the key without scanning.

Get your credentials

Both values come from the XTrace web app:

Sign in at app.xtrace.ai
Open Settings → API Keys (or your organization page)
Copy your Org id and create a new API key (xtk_…)

Treat the API key like a password — anyone with it can read and write memories under your org. Store it in a secrets manager or environment variable, never in source control.

Headers

Authorization: Bearer xtk_...
X-Org-Id: org_...

Both required on every request. Missing or mismatched values:

Error	Cause
`400 missing_org_id`	No `X-Org-Id` header
`401`	Missing or invalid API key
`403 org_mismatch`	`X-Org-Id` doesn’t match the org the key belongs to

Using the SDK

The SDK builds both headers from constructor options:

import { MemoryClient } from '@xtraceai/memory';

const client = new MemoryClient({
  apiKey: process.env.XTRACE_API_KEY!,
  orgId:  process.env.XTRACE_ORG_ID!,
});

That’s it — every method call on the client carries the right headers.

Storing credentials

Never commit API keys to source control. Use environment variables, a secrets manager (AWS Secrets Manager, GCP Secret Manager, 1Password CLI), or a .env file that’s in .gitignore.

A typical setup:

.env

XTRACE_API_KEY=xtk_...
XTRACE_ORG_ID=org_...

import 'dotenv/config';
import { MemoryClient } from '@xtraceai/memory';

const client = new MemoryClient({
  apiKey: process.env.XTRACE_API_KEY!,
  orgId:  process.env.XTRACE_ORG_ID!,
});

Rotating a key

If a key leaks, treat it like any other credential incident:

Issue a new key from your org admin tool
Roll the new key into your environment / secrets manager
Revoke the old key

Keys are long-lived; there is no automatic expiry in v1.

Browser vs server

The SDK works in both Node 18+ and modern browsers (it uses native fetch). Don’t ship API keys to a browser — proxy memory-API calls through your own backend so the key never leaves the server.

Getting started

Guides

Reference

Get your credentials

Headers

Using the SDK

Storing credentials

Rotating a key

Browser vs server

​Get your credentials

​Headers

​Using the SDK

​Storing credentials

​Rotating a key

​Browser vs server

Get your credentials

Headers

Using the SDK

Storing credentials

Rotating a key

Browser vs server