> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xtrace.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> How API keys and org headers work — and how to wire them into the SDK.

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:

1. Sign in at **[app.xtrace.ai](https://app.xtrace.ai)**
2. Open **Settings → API Keys** (or your organization page)
3. 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

```http theme={null}
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:

```ts theme={null}
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

<Note>
  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`.
</Note>

A typical setup:

```bash .env theme={null}
XTRACE_API_KEY=xtk_...
XTRACE_ORG_ID=org_...
```

```ts theme={null}
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:

1. Issue a new key from your org admin tool
2. Roll the new key into your environment / secrets manager
3. 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.