Security
Authentication & API Keys
Every request to the Vivreal Client API is authenticated with an API key. Here's how it works.
How API keys work
Each group in Vivreal has a unique API key. Your frontend includes this key in the Authorization header of every request.
- Generated automatically when a group is created
- Visible to Owners and Admins in the portal settings
- One key per group — rotate by regenerating in settings
- Never expose in client-side code — use server-side fetch only
Authorization flow
The Client API uses a Lambda authorizer that validates your key against MongoDB and injects group context.
- API Gateway receives request with Authorization header
- Lambda authorizer looks up key in MongoDB groups collection
- Returns Allow/Deny IAM policy
- Injects context: database, bucketName, groupID, groupName, tier
Portal authentication (separate)
The portal uses a dual-token cookie system — Cognito JWT + signed context JWT. This is separate from the Client API.
- token cookie — Cognito JWT from login
- active_ctx cookie — HMAC-SHA256 signed context (groupID, dbKey, role, tier)
- Middleware checks token presence, redirects to login if absent
- Edge proxy routes verify active_ctx on every authenticated request
Security layers
Multiple layers of protection across the platform.
- CSRF double-submit cookie on all state-changing proxy routes
- Rate limiting on login: 10 attempts / 15 min per IP
- Integration credentials encrypted with AES-256-GCM in MongoDB
- All secrets stored in AWS Secrets Manager
Secure by Default
Vivreal uses defense in depth — API key auth, JWT verification, CSRF protection, rate limiting, and encrypted credentials. See the full docs for implementation details.