Authentication
Diminuendo supports two authentication methods:
Auth0 JWT
Production authentication via Auth0:
1. Client authenticates with Auth0 and receives a JWT 2. JWT is sent in the Authorization: Bearer <token> header or as WebSocket subprotocol 3. Gateway verifies JWT signature using Auth0 JWKS endpoint (cached with LRU) 4. User identity and tenant are extracted from JWT claims
Dev Mode
When DEV_MODE=true, authentication is bypassed:
- All requests are auto-authenticated as
developer@example.com - Useful for local development without Auth0 setup
RBAC
Roles
| Role | Level | Description |
|---|---|---|
owner | 5 | Full access + billing + tenant deletion |
admin | 4 | Full access except billing |
developer | 3 | CRUD threads/projects, deploy agents |
viewer | 2 | Read-only access |
guest | 1 | Limited thread access |
Permissions
| Permission | Required Role | Description |
|---|---|---|
threads.create | developer | Create new threads |
threads.read | viewer | Read thread history |
threads.write | developer | Send messages, steer, approve |
threads.delete | admin | Delete threads |
projects.create | developer | Create projects |
projects.manage | admin | Manage project settings |
members.manage | admin | Add/remove members, change roles |
integrations.manage | admin | Configure chat integrations |
config.manage | admin | Update tenant settings |
deployments.manage | admin | Deploy agents |
audit.read | admin | Read audit logs |
billing.manage | owner | Manage billing |
Permission Check
requirePermission(identity, 'threads.create');
// Throws 403 if identity.role lacks the required permissionSecurity Features
CSRF Protection
Non-GET requests require a CSRF token (except webhooks and dev mode):
- Token generated per session
- Validated on every mutating request
Rate Limiting
HTTP rate limiting per API key/user:
- Configurable per-endpoint limits
- 429 response with
Retry-Afterheader
Security Headers
All responses include security headers:
X-Content-Type-Options: nosniffX-Frame-Options: DENYStrict-Transport-Security(production)Content-Security-Policy
SSRF Guard
File operations and webhook URLs are validated against SSRF:
- Private IP ranges blocked
- DNS rebinding protection
- Allowlisted domains only
Error Sanitization
Production error responses never leak internal details:
- Stack traces stripped
- Database errors replaced with generic messages
- Request IDs included for correlation