Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/barcode8/VideoHub/llms.txt

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

VideoHub uses a dual-token authentication system: a short-lived access token for authorizing requests and a long-lived refresh token for obtaining new access tokens without re-entering credentials. Both tokens are issued as HttpOnly cookies on login and are also returned in the response body for clients that cannot read cookies directly.

​
Endpoints on this page

MethodPathAuth Required
POST/api/v1/users/registerNo
POST/api/v1/users/loginNo
POST/api/v1/users/logoutYes
POST/api/v1/users/refresh-tokenNo

​
Register a new account

POST /api/v1/users/register Creates a new VideoHub user account. Send fields as a JSON body. Passwords are hashed with bcrypt before storage and are never returned in any response.
Usernames are stored in lowercase and must be unique across the platform. The same uniqueness constraint applies to email addresses.

​
Request parameters

​
username
string
required
Unique handle for the account. Stored in lowercase. Used to identify the user’s public channel at /api/v1/users/c/:username.
​
email
string
required
Valid email address. Must be unique across all accounts.
​
password
string
required
Plain-text password. Hashed with bcrypt (10 salt rounds) before being persisted — never stored in plain text.
​
fullName
string
Display name shown on the channel profile. If omitted, it defaults to the value of username.

​
Response fields

Returns HTTP 201 with a user object. password and refreshToken are always stripped from the response.
​
statusCode
number
Always 200 inside the response envelope (the HTTP status is 201).
​
data
object
The newly created user document.
​
message
string
Human-readable confirmation string, e.g. "User registered successfully".

​
Error responses

StatusCondition
400One or more of username, email, or password is missing or blank.
409An account with the same username or email already exists.
500An internal error occurred after the document was created (rare).

​
Example

curl -X POST http://localhost:5000/api/v1/users/register \
  -H "Content-Type: application/json" \
  -d '{"username": "janedoe", "email": "jane@example.com", "password": "SuperSecret42", "fullName": "Jane Doe"}'

{
  "statusCode": 200,
  "data": {
    "_id": "6650a1f2e4b0c3d9a1234567",
    "username": "janedoe",
    "email": "jane@example.com",
    "fullName": "Jane Doe",
    "avatar": "https://res.cloudinary.com/demo/image/upload/default_avatar.jpg",
    "coverImage": "https://res.cloudinary.com/demo/image/upload/default_cover.jpg",
    "watchHistory": [],
    "createdAt": "2024-05-24T10:00:00.000Z",
    "updatedAt": "2024-05-24T10:00:00.000Z"
  },
  "message": "User registered sucessfully",
  "success": true
}

​
Log in

POST /api/v1/users/login Authenticates a user with either their email or username plus their password. On success, both an accessToken and a refreshToken are issued as HttpOnly cookies (httpOnly: true, secure: false, sameSite: "Lax") and are also included in the JSON response body for non-browser clients.
You can supply either email or username — at least one is required. If both are provided, the server matches against either field.

​
Request parameters

​
email
string
The email address used at registration. Either email or username must be provided.
​
username
string
The account’s username. Either email or username must be provided.
​
password
string
required
The account password in plain text. Compared against the stored bcrypt hash.

​
Response fields

Returns HTTP 200.
​
data.user
object
The authenticated user object with password and refreshToken omitted.
​
data.accessToken
string
Short-lived JWT. Include this in the Authorization: Bearer <token> header for protected endpoints. Also set as the accessToken HttpOnly cookie.
​
data.refreshToken
string
Long-lived JWT. Use this to obtain a new access token via /api/v1/users/refresh-token. Also set as the refreshToken HttpOnly cookie.
​
message
string
"User logged in successfully"

​
Error responses

StatusCondition
400Neither username nor email was provided.
400No account found with the given username or email.
401Password does not match the stored hash.

​
Example

curl -X POST http://localhost:5000/api/v1/users/login \
  -H "Content-Type: application/json" \
  -d '{"email": "jane@example.com", "password": "SuperSecret42"}'

{
  "statusCode": 200,
  "data": {
    "user": {
      "_id": "6650a1f2e4b0c3d9a1234567",
      "username": "janedoe",
      "email": "jane@example.com",
      "fullName": "Jane Doe",
      "avatar": "https://res.cloudinary.com/demo/image/upload/default_avatar.jpg",
      "coverImage": "https://res.cloudinary.com/demo/image/upload/default_cover.jpg",
      "watchHistory": []
    },
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  },
  "message": "User logged in successfully",
  "success": true
}

​
Log out

POST /api/v1/users/logout Terminates the current session. The server clears both accessToken and refreshToken cookies and sets the stored refreshToken field to undefined in the database, preventing the old refresh token from being reused.
This endpoint requires a valid access token. An expired or missing token returns 401 Unauthorized.

​
Request parameters

No request body is required. The user identity is derived from the JWT in the Authorization header or the accessToken cookie.

​
Response fields

​
data
object
An empty object {} — no user data is returned on logout.
​
message
string
"User logged out successfully"

​
Example

curl -X POST http://localhost:5000/api/v1/users/logout \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

{
  "statusCode": 200,
  "data": {},
  "message": "User logged out successfully",
  "success": true
}

​
Refresh an access token

POST /api/v1/users/refresh-token Issues a fresh accessToken (and rotates the refreshToken) without requiring the user to log in again. The endpoint accepts the refresh token from the refreshToken cookie or from the request body.
Rotate your refresh token on every call. The old token is invalidated once a new pair is issued — storing the latest newRefreshToken keeps your session alive without re-authenticating.

​
Request parameters

​
refreshToken
string
The refresh token string. Required if the refreshToken cookie is not present (e.g., in native mobile clients or server-to-server calls).

​
Response fields

Returns HTTP 200. New tokens are set as HttpOnly cookies (accessToken, refreshToken) and also returned in the response body.
​
data.accessToken
string
The newly generated short-lived access token.
​
data.newRefreshToken
string
The newly generated refresh token. Store this and use it for the next refresh call.
​
message
string
"Access token refreshed successfully"

​
Error responses

StatusCondition
401No refresh token found in cookies or request body.
401The token is malformed, expired, or does not match the one stored in the database.

​
Example

# Using the token from a cookie (browser clients handle this automatically)
curl -X POST http://localhost:5000/api/v1/users/refresh-token \
  --cookie "refreshToken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

# Passing the token explicitly in the request body (mobile / server-to-server)
curl -X POST http://localhost:5000/api/v1/users/refresh-token \
  -H "Content-Type: application/json" \
  -d '{"refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}'

{
  "statusCode": 200,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "newRefreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  },
  "message": "Access token refreshed successfully ",
  "success": true
}

Build docs developers (and LLMs) love

Get started for freeTalk to us