Security

Convex runs trusted server-side code, but security still requires:

• consistent authorization checks
• careful storage of secrets and PII
• auditable admin actions

PII classification

PII lives primarily in memberProfiles (name, email, DOB, address, phone) and in support tickets/messages.

Guidelines:

• Avoid duplicating PII in many tables (store references).
• Restrict who can read/export PII.
• Audit admin access to sensitive workflows.

Secrets

Do not store raw CRM/payment provider API keys in Convex documents.

Recommended:

• platform-level secrets: environment variables
• tenant-level credentials: encrypted blob (encryption key in env) or connect through a secure proxy service

Authorization

Use explicit role checks (e.g., ROLE_PLATFORM_ADMIN, ROLE_CLIENT_ADMIN, ROLE_CLIENT_USER, ROLE_MEMBER, ROLE_SPONSOR_ADMIN, ROLE_SPONSOR_USER).

Rules of thumb:

• Reads: allow least privilege needed
• Writes: validate ownership + role + domain invariants
• Never trust client-provided clientId without verifying

Audit logging

Log high-impact actions:

• impersonation
• role changes
• refunds
• integration credential updates

Store audit events in an append-only auditLogs table (tenant-scoped) with actor, action, target, and timestamp.

Features

Security

Acceptance Criteria

Frontend

• Developer-facing configuration and usage is documented and internally consistent.

Backend / API

• Convex implementation matches the rules and contracts described on this page.

Permissions

• Tenant scoping and access controls are enforced as described.

Business Rules

• Domain rules/invariants are enforced as described.

Error Handling

• Access violations and validation failures produce deterministic errors.