Credentials and Server Security
Understand cookie exchange, explicit principals, redaction, and server-boundary controls.
The server boundary treats cookies, bearer session values, and Convex JWTs as credentials. They must remain request-scoped and absent from public error fields.
Credential paths
| Input | Behavior |
|---|---|
| Request Better Auth cookies | Filter relevant cookies and exchange through the configured Convex site |
| Explicit cookie credential | Exchange as a required principal |
| Explicit bearer credential | Exchange as a required principal |
Explicit Convex authToken | Set directly on the request-scoped HTTP client |
auth: 'none' | Skip credential resolution |
Controls
| Threat | Control |
|---|---|
| Credential forwarded to another origin | Token exchange rejects redirects |
| Oversized/malformed exchange response | Bounded response reader and transport classification |
| Header injection | Empty/control-character credentials rejected before fetch |
| Cookie confusion | Cookie and bearer/token paths are mutually constrained |
| Secret leakage in payload/log | cause is non-serialized; public fields are sanitized |
| Cross-request identity reuse | One caller and token promise per request |
Public errors
Authentication and transport failures expose a stable category and safe message. Raw upstream response bodies are not copied into message, code, status, or data.
Structured Convex application errors remain server errors and preserve their application data.
Trusted client IP headers
Configure auth.proxy.trustedClientIpHeader only when a trusted ingress overwrites that header with exactly one client IP. Do not trust a client-supplied forwarding chain.
convex: {
auth: {
proxy: {
trustedClientIpHeader: 'x-platform-client-ip'
}
}
}Application responsibilities
- Validate route bodies and webhook signatures.
- Keep secrets in server or Convex environments.
- Enforce product authorization in Convex.
- Avoid public caching of auth routes and authenticated HTML.
- Redact application logs and monitoring breadcrumbs.
- Rotate compromised secrets and invalidate sessions through Better Auth.
See the broader security model.