Introduction

Userverse is an open-source FastAPI platform for managing users, organizations, roles, and authentication.

Userverse is an open-source platform designed to make managing users, organizations, and their relationships simple and efficient. It is built for developers, communities, and organizations who want a free, flexible, and secure way to handle user and organization management without relying on closed or proprietary systems.

Key features

User management

Register users, handle authentication flows, manage profiles, and control account status with a clean REST API.

Organization support

Create and manage companies, assign members to organizations, and control access through roles and permissions.

JWT authentication

Secure every request with JSON Web Tokens. Configurable secret, algorithm, access token timeout, and refresh token timeout.

Email verification

Built-in email verification flow with SMTP configuration. Resend verification emails without additional setup.

Prometheus metrics

Expose a /metrics endpoint for Prometheus scraping. Tracks unhandled exceptions and is ready for custom instrumentation.

OpenTelemetry tracing

Instrumented with OpenTelemetry for distributed tracing. Exportable via OTLP to your observability backend.

Architecture overview

Userverse is built on a modern Python stack:

Component	Role
FastAPI	Web framework and API layer
PostgreSQL	Primary relational database
SQLAlchemy	ORM and database abstraction
Alembic	Database schema migrations
PyJWT	JWT token generation and validation
Passlib + bcrypt	Secure password hashing
Prometheus client	Metrics collection and exposition
OpenTelemetry	Distributed tracing

Project structure

├── alembic/          # Migration scripts
├── app/
│   ├── database/     # Engine setup, session factory
│   ├── logic/        # Business logic and services
│   ├── middleware/   # CORS, logging, error handlers
│   ├── models/       # Pydantic schemas for validation
│   ├── routers/      # API endpoints by resource domain
│   ├── security/     # JWT and password hashing
│   └── utils/        # Config loader, email, shared helpers
└── tests/            # Unit and integration test suite

Next steps

Quickstart

Clone the repo, install dependencies, and make your first API call in minutes.

API reference

Explore the full list of endpoints for users, companies, and roles.