Skip to content

Agent Authentication

!!! warning "Not Yet Implemented" The Agent IAM system described in ADR-0019 is planned but not yet built. The tables (agent_identities, agent_api_keys, agent_policies, etc.) do not exist in the current schema. This page documents the planned design for future implementation.

Current State

The MCP server endpoints (/api/mcp/tools, /api/mcp/health) currently exist as route handlers but do not have a production authentication mechanism. Agent authentication is on the roadmap (see issues labeled phase-2).

Planned Design (ADR-0019)

The following describes the planned agent authentication system:

API Keys

Agents will authenticate with API keys:

  • Generated as secure random strings (32 bytes, base64-encoded)
  • Hashed with Argon2id before storage (never stored in plaintext)
  • Mapped to an agent identity
  • Revocable without deleting the agent identity

Using an API Key

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

Planned Scopes

Scope Grants Access To
surveys:read List surveys, get details, view results
surveys:write Create, update, delete surveys
surveys:publish Change survey status
responses:read View survey responses and analytics
submissions:read List feedback submissions
submissions:write Create, update submissions
submissions:moderate Moderate and merge duplicates
analytics:read Access aggregated metrics

!!! note "Scope format" Scopes use plural nouns with colon separator (e.g., surveys:read, submissions:write).

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 will be logged to an append-only audit trail.

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

Security Best Practices

  1. Use least privilege — Assign minimal scopes needed
  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