Authentication & security

ConvoMem is built to hold sensitive customer data responsibly. This guide covers how you authenticate and how your data is protected.

API keys

Every request is authenticated with an X-API-Key header:

const res = await fetch('https://api.convomem.com/api/v1/customers?limit=1', {
  headers: {
    'X-API-Key': process.env.CONVOMEM_API_KEY!,
  },
})

The SDK handles auth automatically — pass your key at initialization:

import { ConvoMem } from '@optraze/convomem-sdk'
 
const client = new ConvoMem({
  apiKey: process.env.CONVOMEM_API_KEY!,
})

Keys are bound to one agent

Every API key belongs to exactly one agent — the workspace that owns a given bot or use case (see the memory model). You choose the agent when you create the key, and it cannot be changed afterwards.

That binding decides where your data goes and what comes back:

• Captures land under that agent, and are extracted using that agent's capture prompt
• Recall and lookups return only that agent's memories and conversations
• Webhooks fire only for that agent's events

So two keys behave like two separate datasets, even for the same customer:

const support = new ConvoMem({ apiKey: process.env.SUPPORT_KEY! }) // support agent
const sales   = new ConvoMem({ apiKey: process.env.SALES_KEY! })   // sales agent
 
// Same person — one customer record shared across the organization…
await support.capture(
  [{ role: 'user', content: 'My bag never arrived in Lisbon.' }],
  { email: '[email protected]' },
)
await sales.capture(
  [{ role: 'user', content: 'What would a business class upgrade cost?' }],
  { email: '[email protected]' },
)
 
// …but each key only ever sees its own agent's memories.
const ctx = await support.lookup('recent issues', { email: '[email protected]' })
// → the missing bag, never the upgrade enquiry

If a key's agent is paused or archived in the dashboard, its captures start returning 403 FORBIDDEN until the agent is active again.

Scopes

Organization API keys (sk-org-*) have integration scope and can access:

• Capture (POST /capture)
• Customer management (/customers/*)
• Memory management (/customers/*/memories)
• Conversations (/customers/*/conversations)
• Handoff briefings (/customers/*/handoff, /customers/handoff)
• Live transfer routing (POST /handoff/route)
• Embed tokens (/embed/tokens)

Administrative endpoints — webhooks management, handoff destinations, org settings, audit logs, and analytics dashboards — require session-based authentication through the dashboard. They cannot be accessed with an org API key.

PII redaction

Before an extracted memory is stored, ConvoMem drops any fact that contains credentials or secrets, then applies your organization's sensitive-data policy. By default the policy masks the matched value and keeps the rest of the fact:

Admins can change the categories, switch the action from mask to drop, and (on plans that include it) add custom patterns in the dashboard. Email and phone are off by default because they usually identify the customer rather than describe them. Redaction applies to stored memories; conversation transcripts have their own retention and access controls.

Deployment options

ConvoMem runs as a hosted service at api.convomem.com. For organizations that need the data to stay inside their own infrastructure, an on-premises deployment is available on request — contact [email protected].

What's next

• Quick start — initialize the client and send your first capture
• Embed — browser tokens for client-side widgets

SDK: TypeScript · Python · Rust