Skip to main content

Frequently Asked Questions

Common questions about ConsentKeys authentication.

General​

What is ConsentKeys?​

ConsentKeys is an open-source OpenID Connect (OIDC) identity provider focused on privacy. It provides passwordless authentication using magic links and pseudonymous user profiles.

How is ConsentKeys different from Auth0, Clerk, or Firebase Auth?​

FeatureConsentKeysAuth0/ClerkFirebase Auth
Open Source✅ Yes❌ No❌ No
Privacy-First✅ Pseudonymous profiles⚠️ Optional❌ No
Self-Hosted✅ Yes❌ No❌ No
Passwordless✅ Magic links only⚠️ Optional⚠️ Optional
PricingFree (self-hosted)Paid tiersPaid tiers
Data Control✅ Your infrastructure❌ Their servers❌ Google servers

Is ConsentKeys production-ready?​

Yes, ConsentKeys implements standard OAuth 2.0 and OIDC protocols with security best practices including PKCE, CSRF protection, and JWT verification.

Can I use ConsentKeys for my commercial project?​

Yes! ConsentKeys is MIT licensed. You can use it for any purpose, including commercial projects.

Authentication​

Security benefits:

  • No password reuse across sites
  • No password breaches or leaks
  • Phishing resistant (links are single-use and time-limited)
  • Automatic email verification

User experience benefits:

  • No password to remember
  • Faster login (one click)
  • No "forgot password" flow needed
  • Works seamlessly across devices

Magic links expire after 15 minutes for security. If a link expires, users can request a new one.

What if a user's email is compromised?​

If an attacker gains access to a user's email:

  1. They can authenticate as that user (same as password reset links)
  2. Encourage users to enable 2FA on their email accounts
  3. Implement additional security measures in your app (device fingerprinting, unusual activity detection)
  4. Use short session timeouts for sensitive operations

Email customization is planned for a future release. Currently, emails use a standard template. Configure your application settings in the Developer Portal.

Do you support social logins (Google, GitHub, etc.)?​

Not currently. ConsentKeys focuses on email-based magic link authentication. Social login support may be added in the future.

Privacy​

What data does ConsentKeys store?​

Minimal data:

  • Email address (hashed)
  • Pseudonymous user ID
  • Profile information (only if user provides it)
  • Session data (temporary, encrypted)

Not stored:

  • Passwords (we don't use them!)
  • Tracking data
  • Usage analytics
  • PII unless explicitly provided by the user

What are pseudonymous profiles?​

Each user gets a unique identifier (sub claim) that:

  • Is different for each application
  • Cannot be reverse-engineered to reveal the email
  • Remains consistent across sessions for the same app
  • Prevents cross-application tracking

Example: user_7f8a9b2c1d3e4f5a6b7c8d9e0f1a2b3c

Is ConsentKeys GDPR compliant?​

ConsentKeys follows GDPR principles:

  • ✅ Data minimization (only collect what's needed)
  • ✅ Purpose limitation (data used only for auth)
  • ✅ Storage limitation (sessions expire)
  • ✅ User control (users can delete their data)

However, GDPR compliance also depends on how you use ConsentKeys and handle user data in your application.

Can users delete their data?​

Yes, users can delete their ConsentKeys account which removes all associated data. Implement a data deletion endpoint in your application as well.

Technical​

Do I need a backend server?​

Yes, for security reasons:

  • Your client secret must never be exposed in frontend code
  • The backend exchanges authorization codes for tokens securely
  • Tokens are stored in secure httpOnly cookies

A simple proxy endpoint is sufficient for basic setups.

Can I use ConsentKeys with a single-page app (SPA)?​

Yes! Use the Authorization Code flow with PKCE:

  1. Frontend redirects to ConsentKeys
  2. User authenticates via magic link
  3. Frontend receives authorization code
  4. Backend exchanges code for tokens (required for security)
  5. Backend sets httpOnly cookie
  6. Frontend makes authenticated requests

See the React integration guide for details.

What token format does ConsentKeys use?​

ConsentKeys uses JWT (JSON Web Tokens) signed with RS256:

  • ID tokens: Contain user claims (sub, email, name, etc.)
  • Access tokens: Used to access protected resources
  • Both can be verified using the JWKS endpoint

How long do tokens last?​

  • Access tokens: 1 hour
  • ID tokens: 1 hour
  • Sessions: 7 days (configurable)

Implement token refresh in your application for longer sessions.

Does ConsentKeys support refresh tokens?​

Not currently. When the access token expires, users need to re-authenticate. This is intentional for security - magic links make re-authentication painless.

Can I run ConsentKeys behind a reverse proxy?​

Yes! Make sure to:

  1. Set X-Forwarded-Proto, X-Forwarded-Host headers
  2. Configure CORS properly
  3. Update redirect URIs to use the public URL

What database does ConsentKeys use?​

ConsentKeys uses PostgreSQL for persistent data and Redis for sessions/caching.

Can I scale ConsentKeys horizontally?​

Yes! ConsentKeys is stateless (session data in Redis) so you can run multiple instances behind a load balancer.

Development​

How do I test ConsentKeys?​

  1. Register your application in the Developer Portal
  2. Configure your redirect URI (e.g., http://localhost:3001/callback for local development)
  3. Get your Client ID and Secret
  4. Follow the integration guides to implement authentication

Do I need HTTPS for development?​

No, you can use http://localhost for development. HTTPS is required in production.

How do I debug authentication issues?​

  1. Check the browser console for errors
  2. Enable debug logging in your app
  3. Verify redirect URI matches exactly
  4. Test with cURL to isolate issues
  5. See the Troubleshooting guide

Can I use ConsentKeys with mobile apps?​

Yes! Use custom URL schemes for redirect URIs:

  • iOS: myapp://auth/callback
  • Android: myapp://auth/callback

Configure these in your OAuth client settings.

Does ConsentKeys support webhooks?​

Not currently. Webhooks for user events (signup, login, deletion) are planned for a future release.

Security​

Is PKCE required?​

For public clients (SPAs, mobile apps): Yes, PKCE is required.

For confidential clients (backend servers): PKCE is optional but recommended.

What if my client secret is leaked?​

  1. Immediately regenerate the secret in the Developer Portal
  2. Update your application with the new secret
  3. Old tokens remain valid until they expire

Does ConsentKeys support rate limiting?​

Yes:

  • Magic link requests: 20 per hour per email
  • API calls: 100 per minute (general), 20 per minute (session endpoints)
  • Rate limits return 429 status with RateLimit-* headers

How are sessions secured?​

  • Session cookies are httpOnly (not accessible via JavaScript)
  • Secure flag in production (HTTPS only)
  • SameSite=Lax (CSRF protection)
  • Encrypted with iron-session or similar

Can I implement multi-factor authentication (MFA)?​

ConsentKeys doesn't have built-in MFA yet. You can implement it in your application layer:

  1. Require email MFA (already done via magic links!)
  2. Add TOTP/SMS verification after initial authentication
  3. Use device fingerprinting for additional security

Deployment​

How do I deploy ConsentKeys to production?​

See the Docker deployment guide:

docker-compose up -d

Set these environment variables:

  • DATABASE_URL - PostgreSQL connection
  • REDIS_URL - Redis connection
  • SESSION_SECRET - Strong random key
  • JWT_PRIVATE_KEY - RS256 private key

What are the system requirements?​

Minimum:

  • 1 CPU core
  • 512MB RAM
  • PostgreSQL 12+
  • Redis 6+

Recommended for production:

  • 2+ CPU cores
  • 2GB RAM
  • PostgreSQL 14+
  • Redis 7+

How do I backup ConsentKeys data?​

Backup PostgreSQL database:

pg_dump consentkeys > backup.sql

Redis data is mostly ephemeral (sessions), but can be backed up with RDB/AOF.

Can I use ConsentKeys with Kubernetes?​

Yes! Deploy as a standard containerized application:

  • Use Kubernetes Secrets for sensitive config
  • External PostgreSQL and Redis (managed services)
  • Horizontal Pod Autoscaler for scaling
  • Ingress for routing

Integration​

Can I migrate from another auth provider?​

Yes! Import users with these steps:

  1. Export user emails from your current provider
  2. Create corresponding users in ConsentKeys
  3. Update your application to use ConsentKeys
  4. Users will go through magic link flow on first login

Do you have SDKs for [my language]?​

Currently, there are no official SDKs. ConsentKeys uses standard OAuth 2.0/OIDC, so any OIDC library works.

See integration guides for:

Can I use ConsentKeys with GraphQL?​

Yes! Use the access token in the Authorization header:

query GetUser {
  me {
    id
    email
    name
  }
}
fetch('/graphql', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ query }),
});

Does ConsentKeys work with serverless functions?​

Yes! Use ConsentKeys with:

  • AWS Lambda
  • Vercel Functions
  • Netlify Functions
  • Cloudflare Workers

Store sessions in Redis or a serverless-compatible session store.

Pricing & Licensing​

Is ConsentKeys free?​

Yes! ConsentKeys is open-source (MIT license) and free to self-host.

Will there be a hosted version?​

A managed/hosted version is under consideration. It would offer:

  • Fully managed infrastructure
  • Automatic updates and scaling
  • Premium support
  • Advanced features

How can I support the project?​

  • ⭐ Star the GitHub repository
  • 📝 Contribute code or documentation
  • 🐛 Report bugs and issues
  • 💬 Help others in discussions
  • ☕ Sponsor the project (coming soon)

Still Have Questions?​