Help & Support

Resources, troubleshooting, and direct assistance

Find answers to common questions, get help with implementation, and connect with the ZenoAuth team. From quick fixes to advanced configurations, we have you covered.

Documentation

Comprehensive guides, API references, and implementation examples.

Browse Docs

Troubleshooting

Common issues, error codes, and step-by-step solutions.

Get Help

Community

Connect with other developers, share experiences, and get peer support.

Join Community

Direct Support

Technical support for implementation issues and enterprise deployments.

Contact Us

Common Issues & Solutions

Installation & Setup Issues

Database Connection Failed

Most common cause: incorrect DATABASE_URL format

Solution
# Correct format: export DATABASE_URL="postgresql://username:password@localhost:5432/zenoauth" # Test connection: psql $DATABASE_URL -c "SELECT version();" # Verify database exists: createdb zenoauth

Port Already in Use

ZenoAuth can't bind to the default port 3051

Solution
# Check what's using port 3051: lsof -i :3051 # Use different port: export ZENOAUTH__SERVER__PORT=3052 ./target/release/zenoauth # Or in docker-compose.yml: ports: - "3052:3051"

JWT Signing Key Issues

Ed25519 signing key not generated or invalid

Solution
# Ed25519 keys are auto-generated on startup # Verify JWKS endpoint is accessible: curl http://localhost:3051/oauth/jwks # Check server logs for key generation: docker-compose logs zenoauth | grep "key manager" # If persisting keys, use base64-encoded Ed25519: # export ZENOAUTH__SECURITY__SIGNING_KEY="base64..."

OAuth & Authentication Issues

Invalid Client Credentials

OAuth client not found or credentials mismatch

Solution
# Verify client exists via admin API: curl -H "Authorization: Bearer $ADMIN_TOKEN" \ http://localhost:3051/admin/clients # Create new client if needed: curl -X POST http://localhost:3051/admin/clients \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $ADMIN_TOKEN" \ -d '{ "name": "My App", "redirect_uris": ["http://localhost:3000/callback"], "scopes": ["openid", "profile", "email"] }'

Token Validation Errors

JWT signature verification or expiration issues

Solution
# Check token introspection: curl -X POST http://localhost:3051/oauth/introspect \ -H "Authorization: Basic $CLIENT_CREDENTIALS" \ -d "token=$ACCESS_TOKEN" # Verify JWKS endpoint: curl http://localhost:3051/oauth/jwks # Check server logs for details: docker-compose logs zenoauth

Performance & Production Issues

High Memory Usage

Memory consumption growing over time

Solution
# Tune cache settings: export ZENOAUTH__CACHE__MAX_SIZE=1000 export ZENOAUTH__CACHE__TTL=3600 # Monitor memory usage: docker stats zenoauth-container # Set memory limits: docker run --memory=512m zenoauth:latest

Slow Response Times

Authentication taking longer than expected

Solution
# Optimize database connections: export ZENOAUTH__DATABASE__MAX_CONNECTIONS=20 export ZENOAUTH__DATABASE__MIN_CONNECTIONS=5 # Enable query optimization: export ZENOAUTH__DATABASE__STATEMENT_TIMEOUT=30s # Check database indexes: psql $DATABASE_URL -c "\d+ users"

Community & Resources

Customer Support

  • Bug Reports
    Report problems and get help from our support team
  • Technical Questions
    Get expert answers to implementation questions
  • Feature Requests
    Suggest new features for our roadmap
  • Enterprise Support
    Priority assistance for enterprise customers
Contact Support

Learning Resources

  • API Documentation
    Complete reference for all 157+ endpoints
  • Integration Examples
    Sample integrations and real-world use cases
  • Architecture Guide
    Deep-dive into ZenoAuth's design and components
  • Deployment Guide
    Production deployment best practices
View Documentation

Community Guidelines

Our community values respect, collaboration, and constructive feedback. When asking for help:

Be Specific

Include error messages, configuration details, and steps to reproduce

Search First

Check existing issues and documentation before posting

Help Others

Share your knowledge and contribute back to the community

Direct Support Options

Email Support

For technical support, implementation questions, and enterprise inquiries, reach out to our support team.

Support Email

[email protected]

When contacting support, include:

  • ZenoAuth version
  • Operating system and environment details
  • Complete error messages and logs
  • Steps to reproduce the issue
  • Expected vs actual behavior

Enterprise Support

For enterprise deployments, custom integrations, and priority support, we offer dedicated assistance.

Enterprise Includes:

  • Priority email support (24h response time)
  • Dedicated deployment assistance
  • Custom integration consulting
  • Performance optimization guidance
Contact Enterprise Support

Support Hours & Response Times

Community Support

GitHub issues and discussions
Response: Best effort

Email Support

Technical questions
Response: 48-72 hours

Enterprise Support

Priority assistance
Response: 24 hours

Frequently Asked Questions

Is ZenoAuth production-ready?

Yes. ZenoAuth is designed for production use with comprehensive security features, audit logging, and enterprise-grade reliability. It ships as a single 16 MB binary with ~50 MB memory footprint at runtime.

What databases are supported?

ZenoAuth supports PostgreSQL 12+ as the sole external dependency. This single-dependency architecture simplifies deployment and maintenance while providing excellent performance and reliability. No Redis, no message queues, no external cache.

Can I migrate from other OAuth providers?

Yes. ZenoAuth provides standard-compliant OAuth 2.0 and OIDC endpoints, making migration from providers like Auth0, Keycloak, and custom implementations straightforward. Contact support for assistance with specific migration scenarios.

What's the licensing model?

ZenoAuth offers both cloud SaaS and self-hosted licensing options. Visit our pricing page for current plans and details.