Basic Auth

Use HTTP Basic Auth to register, log in, and reset your password. Userverse validates your credentials and returns a JWT token pair.

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)>

For example, the credentials [e-mail]:s3cr3t encode to:

echo -n "[e-mail]:s3cr3t" | base64
# YWRhQGV4YW1wbGUuY29tOnMzY3IzdA==

Which produces the header:

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

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 "[e-mail]:s3cr3t" \
  -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": "[e-mail]",
    "phone_number": "1234567890",
    "status": "Awaiting Verification: User must verify their email",
    "is_superuser": false
  }
}

Log in

Log in to receive a JWT access token and refresh token.

curl -X PATCH http://localhost:8501/user/login \
  -u "[e-mail]:s3cr3t"

A successful response returns the token pair:

{
  "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"
  }
}

Save the access_token — you will pass it as a Bearer token for all subsequent authenticated requests.

Reset password

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 "[e-mail]:newpassword"

A successful response confirms the password was changed:

{
  "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.