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.
HTTP Basic Auth is used for the small set of endpoints where Userverse needs to verify your identity before issuing or replacing a JWT token. You do not use Basic Auth for general API calls — only for the entry-point and credential-change endpoints listed below.
How it works
The HTTP Basic Auth scheme encodes your credentials as username:password in base64 and sends them in the Authorization request header. Userverse treats your email address as the username and your password as the password.
Authorization: Basic <base64(email:password)>
ada@example.com:s3cr3t encode to:
echo -n "ada@example.com:s3cr3t" | base64
# YWRhQGV4YW1wbGUuY29tOnMzY3IzdA==
Authorization: Basic YWRhQGV4YW1wbGUuY29tOnMzY3IzdA==
When using curl, you can pass the -u "email:password" flag and curl encodes and sends the header automatically — no manual base64 step required.
Endpoints that require Basic Auth
| Method | Path | Purpose |
|---|
POST | /user/create | Register a new user account |
PATCH | /user/login | Log in and receive a JWT token pair |
PATCH | /password-reset/validate-otp | Validate a one-time PIN and set a new password |
For PATCH /password-reset/validate-otp, pass your email as the username and your new password as the password. The endpoint also requires the OTP you received by email, passed as the one_time_pin query parameter.
Examples
Create user
Log in
Reset password
Register a new account. Pass optional profile fields in the JSON body alongside your Basic Auth credentials.curl -X POST http://localhost:8501/user/create \
-u "ada@example.com:s3cr3t" \
-H "Content-Type: application/json" \
-d '{
"first_name": "Ada",
"last_name": "Lovelace",
"phone_number": "1234567890"
}'
{
"message": "User created successfully",
"data": {
"id": 1,
"first_name": "Ada",
"last_name": "Lovelace",
"email": "ada@example.com",
"phone_number": "1234567890",
"status": "Awaiting Verification: User must verify their email",
"is_superuser": false
}
}
Log in to receive a JWT access token and refresh token.curl -X PATCH http://localhost:8501/user/login \
-u "ada@example.com:s3cr3t"
{
"message": "User logged in successfully",
"data": {
"token_type": "bearer",
"access_token": "<your-access-token>",
"access_token_expiration": "2026-04-01 10:30:00",
"refresh_token": "<your-refresh-token>",
"refresh_token_expiration": "2026-04-01 11:00:00"
}
}
access_token — you will pass it as a Bearer token for all subsequent authenticated requests. After requesting a password reset (PATCH /password-reset/request), you receive an OTP by email. Pass it as one_time_pin, with your email as the username and your new password as the password.curl -X PATCH "http://localhost:8501/password-reset/validate-otp?one_time_pin=123456" \
-u "ada@example.com:newpassword"
{
"message": "Password changed successfully",
"data": null
}
Error responses
| Status | Message | Cause |
|---|
401 Unauthorized | "Invalid credentials" | Missing email, missing password, invalid email format, or wrong password |
401 Unauthorized | "Invalid credentials" | Malformed or missing Authorization header |
Userverse returns the same "Invalid credentials" message for both missing fields and wrong passwords. This is intentional — it avoids leaking whether an email address is registered.
Next steps
Once you have an access token from PATCH /user/login, read the JWT authentication page to learn how to pass it in requests to protected endpoints.