Skip to main content

API Keys

API keys authenticate external services — Zapier, n8n, and custom HTTP integrations — against your Konvoq account. Each key carries a set of scopes that control exactly what it can access.

Manage keys at Dashboard → Settings → API Keys.

Creating an API key​

  1. Go to Dashboard → Settings → API Keys
  2. Click New API Key
  3. Enter a descriptive name (e.g. Zapier production, n8n self-hosted)
  4. Select the scopes your integration needs (see table below)
  5. Optionally set an expiry date — useful for short-lived integrations
  6. Click Create

:::warning Key shown once The full API key is displayed only at creation. Copy it immediately and store it securely. If lost, revoke the key and create a new one. :::

The key format is knq_live_... — you'll see a short prefix in the dashboard (e.g. knq_live_abc1) for identification.

Scopes​

Scopes limit what each key can do. Grant only what your integration actually needs.

ScopeWhat it allows
read:leadsRead lead records — list, search, fetch by ID
write:leadsCreate and update leads, change pipeline stage
read:conversationsRead conversation history and session data
write:conversationsSend messages to active handoff sessions
webhooksCreate, update, and delete webhook subscriptions
IntegrationMinimum scopes
Zapier (trigger only)webhooks
Zapier (trigger + lead actions)webhooks, read:leads, write:leads
n8n (receive events)webhooks
n8n (receive events + write leads)webhooks, write:leads
Custom backend (read only)read:leads, read:conversations

Using a key​

Pass the key as a Bearer token in the Authorization header on every request:

GET /api/public/zapier/me HTTP/1.1
Host: chat.konvoq.com
Authorization: Bearer knq_live_your_key_here

Revoking a key​

  1. Go to Dashboard → Settings → API Keys
  2. Click the trash icon next to the key
  3. Confirm — the key is invalidated immediately

Any integration using that key will start receiving 401 Unauthorized responses. Update the integration with a new key before revoking the old one to avoid downtime.

Security best practices​

  • One key per integration — makes it easy to revoke one without affecting others
  • Minimal scopes — don't grant write:leads if the integration only reads data
  • Set expiry dates for temporary integrations or contractors
  • Never commit keys to source control — use environment variables or secret managers
  • Rotate keys periodically — especially after team member offboarding