Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/aliammari1/readrealm/llms.txt

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

The ReadRealm API uses JSON Web Tokens (JWT) for authentication. After logging in, include the token in every request to a protected endpoint using the Authorization: Bearer header.
All authentication endpoints are prefixed with /auth.

​
Register a new account

POST /auth/register Creates a new user account. Returns a success message — no token is issued at registration.

​
Request body

​
username
string
required
Display name for the account.
​
email
string
required
A valid email address. Must be unique across all accounts.
​
password
string
required
Account password. Minimum 6 characters.
​
profilePicture
string
URL or path to the user’s profile picture. Optional.

​
Response

​
message
string
Confirmation message on success. Value: "User registered successfully".

​
Example

curl --request POST \
  --url http://localhost:3000/auth/register \
  --header 'Content-Type: application/json' \
  --data '{
    "username": "jane",
    "email": "jane@example.com",
    "password": "secret123"
  }'

​
Log in

POST /auth/login Authenticates an existing user and returns a JWT access token and a refresh token.

​
Request body

​
email
string
required
The account email address.
​
password
string
required
The account password. Minimum 6 characters.

​
Response

​
accessToken
string
JWT used to authenticate subsequent API requests. Expires after 1 hour.
​
refreshToken
string
UUID token used to obtain a new access token. Valid for 3 days.
​
userId
string
Unique identifier of the authenticated user.

​
Example

curl --request POST \
  --url http://localhost:3000/auth/login \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "jane@example.com",
    "password": "secret123"
  }'

​
Use the token in requests

Pass the accessToken from the login response in the Authorization header of every request to a protected endpoint. 
curl --request GET \
  --url http://localhost:3000/users/me \
  --header 'Authorization: Bearer <your_access_token>'
The access token expires after 1 hour. Requests made with an expired or missing token return 401 Unauthorized.

​
Change password

PUT /auth/change-password Updates the password for the currently authenticated user. Requires a valid JWT.

​
Request headers

​
Authorization
string
required
Bearer <your_access_token>

​
Request body

​
oldPassword
string
required
The user’s current password.
​
newPassword
string
required
The replacement password.

​
Response

​
message
string
Confirmation on success. Value: "Password changed successfully".

​
Example

curl --request PUT \
  --url http://localhost:3000/auth/change-password \
  --header 'Authorization: Bearer <your_access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "oldPassword": "secret123",
    "newPassword": "newSecret456"
  }'

​
Email verification

ReadRealm uses a one-time password (OTP) flow to verify email addresses. The OTP is sent to the user’s email inbox.
1

Request an OTP

Call POST /auth/generate-email with the user’s email address. The API sends an OTP to that address.
​
email
string
required
The email address to verify.
curl --request POST \
  --url http://localhost:3000/auth/generate-email \
  --header 'Content-Type: application/json' \
  --data '{"email": "jane@example.com"}'
Response:
​
message
string
Value: "OTP sent successfully".
2

Submit the OTP

Call POST /auth/verify-email with the email address and the OTP from the inbox.
​
email
string
required
The email address being verified.
​
otp
string
required
The one-time password received by email.
curl --request POST \
  --url http://localhost:3000/auth/verify-email \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "jane@example.com",
    "otp": "123456"
  }'
Response:
​
message
string
Value: "Email verified successfully" on success. Returns 422 Unprocessable Entity if the OTP is invalid or expired.

​
Forgot password

POST /auth/forgot-password Resets the password for an account identified by email address. No authentication token is required.
Verify the user’s email address before allowing a password reset to prevent unauthorized account takeover.

​
Request body

​
email
string
required
The email address of the account to update.
​
password
string
required
The new password to set for the account.

​
Response

​
message
string
Confirmation on success. Value: "Password changed successfully".

​
Example

curl --request POST \
  --url http://localhost:3000/auth/forgot-password \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "jane@example.com",
    "password": "brandNewPassword789"
  }'