Authentication - Memory Crystal

If Memory Crystal is a vault, the API key is the key that opens the vault. No key means no memory access.

What this means in practice

Most HTTP-facing access uses:

Authorization: Bearer <api-key>

You may also see environment variables like:

MEMORY_CRYSTAL_API_KEY
MEMORY_CRYSTAL_API_URL

Those are especially important for MCP client and server setup.

How it actually works

Authentication happens at two layers:

1. API Key Creation Flow

When a user wants to use Memory Crystal via HTTP or MCP, they first generate an API key:

User action: Request new API key (via dashboard or API)
  ↓
Backend: `issueApiKeyForUser({ userId, label })`
  ↓
Generate: 32 random bytes → hex string (raw key returned once)
  ↓
Store: SHA256 hash of key in `crystalApiKeys` table
  ↓
Return: Raw key to user (never stored plaintext)

Why hash the key? If the database is compromised, attackers can’t immediately use the key. The user only sees the raw key once during creation.

2. HTTP Request Authentication

Every HTTP request must include the key as a Bearer token:

Authorization: Bearer <api-key>

The backend validates this by:

Extract Bearer token from header
SHA256 hash it
Query crystalApiKeys for a matching hash
Check if key is active and not expired
Check if key belongs to the authenticated user
Fire-and-forget: update lastUsedAt timestamp

If any check fails: 401 Unauthorized

3. MCP Server Configuration

For MCP transport, set environment variables:

MEMORY_CRYSTAL_API_URL=https://your-deployment.convex.site
MEMORY_CRYSTAL_API_KEY=your_raw_api_key

The MCP server forwards these to HTTP endpoints as Bearer tokens.

4. Rate Limiting Integration

After auth succeeds, rate limits are checked immediately:

Auth success → checkAndIncrementRateLimit(userId, tier)
  ↓
Check: requests this minute < tier limit?
  ↓
If yes: increment counter, return 200 + results
If no:  return 429 + Retry-After header

Rate limits are per-endpoint and per-tier (Free/Pro/Ultra).

HTTP Status Codes

200 OK

Request authenticated and processed successfully.

401 Unauthorized

Missing Authorization header
Malformed header (not Bearer <token>)
Bearer token doesn’t match any known key hash
Key is inactive (disabled by user)
Key has expired (expiresAt < now)
Key belongs to a different user

Response:

{ "error": "Unauthorized" }

403 Forbidden

The authenticated user is not allowed to access this resource. Examples:

Memory belongs to a different user
Knowledge base is scoped to a channel the user is not in
User’s tier doesn’t support this operation

Response:

{ "error": "Forbidden" }

429 Too Many Requests

Rate limit exceeded for the user’s tier. Response headers:

Retry-After: <seconds>
X-RateLimit-Limit: <requests-per-minute>
X-RateLimit-Remaining: <requests-left>
X-RateLimit-Reset: <unix-timestamp>

Response body:

{ "error": "Rate limit exceeded", "retryAfterMs": 12000 }

Commands / examples

Example process-level configuration (MCP):

MEMORY_CRYSTAL_API_URL=https://your-deployment.convex.site \
MEMORY_CRYSTAL_API_KEY=your_api_key_here \
npm run start --workspace mcp-server

Example HTTP request (with curl):

curl -X POST https://your-deployment.convex.site/api/mcp/recall \
  -H "Authorization: Bearer $MEMORY_CRYSTAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "authentication flow",
    "limit": 5
  }'

Example creating an API key (via Convex):

// From dashboard or internal API
const rawKey = await ctx.runMutation(internal.crystal.mcp.issueApiKeyForUser, {
  userId: user.id,
  label: "claude-session-key"
});
// rawKey is returned ONCE — user must save it immediately

0.7.15 — API-key recall path improvements

As of 0.7.15, the API-key (HTTP) path of crystal_why_did_we, crystal_who_owns, crystal_dependency_chain, and crystal_explain_connection now forwards the channel parameter to the backend recall endpoint. Previously these four tools silently dropped channel on the API-key branch, returning unscoped cross-channel results. JWT clients were already correct; hosted/API-key consumers should now pass channel when peer scoping is desired.

Common mistakes

mixing CRYSTAL_API_KEY and MEMORY_CRYSTAL_API_KEY without understanding which layer is consuming them
forgetting the backend URL for MCP server setups
assuming local install success means auth is valid

Source of truth

Primary files behind this page:

.env.example
packages/mcp-server/README.md
mcp-server/README.md
convex/crystal/mcp.ts
convex/crystal/knowledgeHttp.ts
scripts/crystal-doctor.sh

​What this means in practice

​How it actually works

​1. API Key Creation Flow

​2. HTTP Request Authentication

​3. MCP Server Configuration

​4. Rate Limiting Integration

​HTTP Status Codes

​200 OK

​401 Unauthorized

​403 Forbidden

​429 Too Many Requests

​Commands / examples

​0.7.15 — API-key recall path improvements

​Common mistakes

​Source of truth