Skip to main content

​
How configuration works

Userverse loads its settings from a JSON file at startup. The path to that file is resolved from the JSON_CONFIG_PATH environment variable. 
export JSON_CONFIG_PATH=/path/to/your/config.json
If JSON_CONFIG_PATH is not set, the application falls back to the [tool.userverse.config] section of pyproject.toml. If neither is available, a minimal default test configuration is used.
Always set JSON_CONFIG_PATH in production. Relying on pyproject.toml defaults is only appropriate during local development.

​
Sample configuration

The repository ships with sample-config.json as a starting point. Copy it and update the values before starting the server. 
{
    "server_url": "http://localhost:8501",
    "name": "Userverse",
    "cor_origins": {
        "allowed": [
            "*"
        ],
        "blocked": [
            "http://localhost:30XX"
        ]
    },
    "jwt": {
        "SECRET": "your_jwt_secret",
        "ALGORITHM": "HS256",
        "TIMEOUT": 30,
        "REFRESH_TIMEOUT": 60
    },
    "email": {
        "HOST": "mail.example.com",
        "PORT": 587,
        "USERNAME": "your_email@example.com",
        "PASSWORD": "your_email_password"
    }
}

​
Configuration reference

​
Top-level fields

​
server_url
string
default:"http://localhost:8000"
The base URL of the server. Used in generated links such as email verification URLs.
​
name
string
default:"Userverse"
The display name of the application. Appears in the OpenAPI docs title and in the root endpoint response.

​
CORS origins (cor_origins)

Controls which origins are permitted to make cross-origin requests to the API.
​
cor_origins.allowed
string[]
default:"[\"*\"]"
List of allowed origins. Use "*" to permit all origins. In production, restrict this to your frontend domain(s).
​
cor_origins.blocked
string[]
List of origins to explicitly block, even if they appear in allowed. Origins present in both lists are denied.

​
JWT (jwt)

Replace jwt.SECRET with a long, randomly generated string before deploying to any non-local environment. Never commit the secret to version control.
​
jwt.SECRET
string
required
The secret key used to sign and verify JWT tokens. Use a strong, random value of at least 32 characters.
​
jwt.ALGORITHM
string
default:"HS256"
The signing algorithm for JWTs. HS256 is the default. Other HMAC algorithms such as HS384 and HS512 are also valid.
​
jwt.TIMEOUT
number
default:"30"
Lifetime of an access token in minutes. After this period the token expires and the user must log in again or exchange a refresh token.
​
jwt.REFRESH_TIMEOUT
number
default:"60"
Lifetime of a refresh token in minutes. This should be longer than TIMEOUT to allow silent token renewal.

​
Email (email)

Required for the email verification and password reset flows. Userverse connects to your SMTP server to send transactional emails.
​
email.HOST
string
required
Hostname of your SMTP server (e.g., mail.example.com or smtp.gmail.com).
​
email.PORT
number
default:"587"
SMTP port. Use 587 for STARTTLS (recommended) or 465 for SSL.
​
email.USERNAME
string
required
The email address or username used to authenticate with the SMTP server.
​
email.PASSWORD
string
required
The password for the SMTP account. Store this securely and never commit it to version control.