Skip to content

Agent Authentication

!!! info "TL;DR" Agents authenticate with a scoped API key (pk_live_... or pk_test_...) passed as a bearer token. Keys are verified against an Argon2id hash and mapped to a policy of permission scopes. The key must be agent-backed, created from the Agent Management page, not the generic API Keys wizard or the SDK page. See the MCP integration guide for the complete reference.

Current State

Agent authentication (ADR-0019) is implemented. The MCP server endpoints (/api/mcp/tools, /api/mcp/health) authenticate every request against a scoped API key and enforce the caller's permission scopes before any tool executes.

Key types

Canviq issues three kinds of API key. They all look the same (same pk_live_/pk_test_ prefix, same length), but only one of them works here.

Key type Created from Authenticates against Used by
rest Settings → API Keys The REST API Server-to-server integrations
sdk Settings → API Keys (SDK page) /api/sdk/* The iOS SDK, web embed
mcp Agent Management (/admin/settings/agents) /api/mcp/tools AI agents, the canviq CLI

The CLI and the MCP tools API require an agent-backed mcp key. The MCP auth check (src/lib/mcp/middleware.ts) rejects any key whose row has no linked agent, and the only place that produces a linked key is Agent Management: create or open an agent there, then generate its key from that agent's own page. A key created through the generic API Keys wizard by selecting "MCP" as the key type is not linked to an agent and will fail with 401 Invalid API key on every MCP or CLI request, even though the key looks valid and the wizard let you create it. The same is true of an SDK key: it authenticates fine against /api/sdk/*, but the MCP endpoint will reject it for the same reason.

How to tell which key you have: you can't, from the string alone. All three share the pk_live_/pk_test_ format. Track it by where you created it, or check the key's badge (REST / SDK / MCP) on the Settings → API Keys list. A key listed there with an "MCP" badge is still not guaranteed to be agent-backed if it predates Agent Management being wired up correctly for your account. When in doubt, generate a fresh key from the agent's own page and use that one.

API Keys

Agents authenticate with API keys:

  • Prefixed by environment: pk_live_... for production data, pk_test_... for sandbox data
  • Verified against an Argon2id hash stored at rest; the plaintext is never persisted
  • Mapped to a policy of permission scopes
  • Revocable without deleting the agent identity

Using an API Key

curl -X POST https://canviq.app/api/mcp/tools \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{...}'

Permission scopes

Scope Grants Access To
surveys:read List and view surveys, responses, and triggers
surveys:write Create, update, publish, pause, and archive surveys, questions, and triggers
pmf:read View PMF scores and segment breakdowns
* Full access to every tool. High-privilege; grant sparingly.

!!! note "Scope format" Scopes pair a resource noun with an action, separated by a colon (for example, surveys:read, surveys:write). The wildcard * is a separate high-privilege grant, not a per-capability scope.

Planned Rate Limits (Upstash Redis)

Tier Requests Window
Standard 60 1 minute
Professional 300 1 minute
Enterprise 1000 1 minute

Audit Logging

All agent actions are logged to an append-only audit trail.

!!! danger "PII Redaction" Audit log params fields must not store PII (emails, IP addresses) in plaintext. Field-level redaction is applied before logging sensitive data.

Security Best Practices

  1. Use least privilege: assign the minimal scopes an agent needs.
  2. Rotate keys regularly: generate new keys every 90 days.
  3. Set key expiration: use expires_at for temporary agents.
  4. Monitor audit logs: set up alerts for suspicious patterns.
  5. Redact PII: never log sensitive user data in plaintext.

What's Next