Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/SoftwareVerse/userverse/llms.txt

Use this file to discover all available pages before exploring further.

1

Clone the repository

Clone the Userverse repository from GitHub and enter the project directory.
git clone https://github.com/SoftwareVerse/userverse.git
cd userverse
2

Install dependencies

Userverse uses uv for dependency management. Install all dependencies with:
uv sync
You need Python 3.12 or later and uv installed. If you don’t have uv, install it with pip install uv.
3

Configure the application

Copy the sample configuration file and update it with your settings:
cp sample-config.json config-dev.json
At minimum, update the jwt.SECRET and the email block before starting the server. See the configuration reference for a full description of every option.
4

Start the server

Choose the mode that fits your workflow.
export ENV=development
export JSON_CONFIG_PATH=config-dev.json
uvicorn app.main:create_app --factory --reload --host 0.0.0.0 --port 8501
Development mode supports live code reload via --reload and is ideal for local development. CLI mode supports multiple Uvicorn workers for production scaling but does not enable reload.
Once the server is running, visit http://localhost:8501 (or whichever port you chose). You should see:
{
  "status": "ok",
  "name": "Userverse",
  "message": "Welcome to the Userverse backend API"
}
5

Create your first user

The POST /user/create endpoint uses HTTP Basic Auth — pass your email as the username and your desired password as the password.
curl -X POST http://localhost:8501/user/create \
  -u "you@example.com:yourpassword" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Ada",
    "last_name": "Lovelace",
    "phone_number": "1234567890"
  }'
A successful response returns the created user:
{
  "message": "User created successfully",
  "data": {
    "id": 1,
    "first_name": "Ada",
    "last_name": "Lovelace",
    "email": "you@example.com",
    "phone_number": "1234567890",
    "status": "Awaiting Verification: User must verify their email",
    "is_superuser": false
  }
}
6

Log in to get a token

Call PATCH /user/login with your credentials using HTTP Basic Auth. Userverse returns a JWT access token and a refresh token.
curl -X PATCH http://localhost:8501/user/login \
  -u "you@example.com:yourpassword"
Save the access_token from the response — you will need it for authenticated requests.
{
  "message": "User logged in successfully",
  "data": {
    "token_type": "bearer",
    "access_token": "<your-jwt-token>",
    "access_token_expiration": "2026-04-01 10:00:00",
    "refresh_token": "<your-refresh-token>",
    "refresh_token_expiration": "2026-04-01 11:00:00"
  }
}
7

Make an authenticated request

Pass the access token as a Bearer token in the Authorization header to call protected endpoints.
curl -X GET http://localhost:8501/user/get \
  -H "Authorization: Bearer <your-jwt-token>"
A successful response returns your user profile:
{
  "message": "User found",
  "data": {
    "id": 1,
    "first_name": "Ada",
    "last_name": "Lovelace",
    "email": "you@example.com",
    "phone_number": "1234567890",
    "status": "Awaiting Verification: User must verify their email",
    "is_superuser": false
  }
}
Tokens expire based on the jwt.TIMEOUT value in your config (default: 30 minutes). Re-authenticate via PATCH /user/login to obtain a new token pair.

Build docs developers (and LLMs) love

Get started for freeTalk to us