Skip to main content
All auth endpoints are served under the /api/auth prefix. None of the endpoints in this group require an existing valid session — they are the entry points for establishing one.
The refreshToken is stored as an HttpOnly cookie after a successful login. The accessToken returned in the JSON body should be stored in memory (not localStorage) and passed as a Bearer token on subsequent requests.

​
POST /api/auth/register

Begin the registration flow. Sends a one-time password to the provided email address. The user record is not created until OTP verification succeeds. Auth required: No

​
Request body

​
name
string
required
Full display name for the new account.
​
email
string
required
Email address. Must be unique across all accounts.
​
password
string
required
Plain-text password. Hashed before storage. Not required when using Google login.
​
role
string
required
Account role. One of freelancer or client. The admin role cannot be self-registered.
​
mobile
string
Optional phone number.

​
Response

​
message
string
Confirmation that the OTP was sent to the provided email.
cURL
curl -X POST https://your-backend-domain.com/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alex Johnson",
    "email": "[email protected]",
    "password": "securepassword",
    "role": "freelancer"
  }'

​
POST /api/auth/verify-otp

Verify the OTP and create the user account. Call this immediately after /register. Auth required: No

​
Request body

​
email
string
required
The email address used during registration.
​
otp
string
required
The six-digit code sent to the email address.
​
userData
object
required
The same registration payload originally submitted to /register.

​
Response

​
message
string
Confirmation that the account was created successfully.
cURL
curl -X POST https://your-backend-domain.com/api/auth/verify-otp \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "otp": "482910",
    "userData": {
      "name": "Alex Johnson",
      "email": "[email protected]",
      "password": "securepassword",
      "role": "freelancer"
    }
  }'

​
POST /api/auth/resend-otp

Request a new OTP for the given email address. Use this when the original code expires or is not received. Auth required: No

​
Request body

​
email
string
required
Email address that was used during registration.

​
Response

​
message
string
Confirmation that a new OTP was dispatched.
cURL
curl -X POST https://your-backend-domain.com/api/auth/resend-otp \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

​
POST /api/auth/login

Authenticate with email and password. On success, sets an HttpOnly refreshToken cookie and returns a short-lived accessToken in the response body. Auth required: No

​
Request body

​
email
string
required
Registered email address.
​
password
string
required
Account password.

​
Response

​
message
string
Human-readable status message.
​
accessToken
string
Short-lived JWT. Pass this in the Authorization: Bearer header on protected requests.
​
role
string
Role of the authenticated user: freelancer, client, or admin.
​
user
object
Blocked accounts receive a 403 error and cannot log in until an admin unblocks them.
cURL
curl -X POST https://your-backend-domain.com/api/auth/login \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{
    "email": "[email protected]",
    "password": "securepassword"
  }'

​
POST /api/auth/logout

Clear the refreshToken cookie, ending the session. Auth required: No (cookie is cleared regardless)

​
Response

​
message
string
Confirmation of successful logout.
cURL
curl -X POST https://your-backend-domain.com/api/auth/logout \
  -b cookies.txt \
  -c cookies.txt

​
POST /api/auth/refresh-token

Issue a new accessToken using the refreshToken cookie. Call this when the current access token expires (after 2 hours). Auth required: No (uses the refreshToken cookie)

​
Request

No request body. The server reads the refreshToken from the HttpOnly cookie automatically.

​
Response

​
accessToken
string
A new short-lived JWT access token.
The browser must include credentials (cookies) for this request. In fetch, set credentials: "include". In axios, set withCredentials: true.
cURL
curl -X POST https://your-backend-domain.com/api/auth/refresh-token \
  -b cookies.txt

​
POST /api/auth/google-login

Authenticate or register using a Google OAuth ID token. If the email is not yet registered, a new account is created automatically. Auth required: No

​
Request body

​
token
string
required
Google OAuth ID token obtained from the Google Sign-In SDK.
​
role
string
required
Role to assign if a new account is being created. One of freelancer or client. Ignored for returning users.

​
Response

Same shape as POST /api/auth/login: message, accessToken, role, and user. The refreshToken cookie is also set.
cURL
curl -X POST https://your-backend-domain.com/api/auth/google-login \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{
    "token": "eyJhbGciOiJSUzI1NiIsImtpZCI6...",
    "role": "client"
  }'

​
POST /api/auth/forgot-password

Send a password-reset link to the registered email address. The link contains a short-lived signed token. Auth required: No

​
Request body

​
email
string
required
Email address associated with the account.

​
Response

​
message
string
Confirmation that the reset email was dispatched.
cURL
curl -X POST https://your-backend-domain.com/api/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

​
POST /api/auth/update-new-password

Complete the forgot-password flow by submitting the reset token and a new password. The token is extracted from the link sent by /forgot-password. Auth required: No

​
Request body

​
token
string
required
The signed reset token from the password-reset email link.
​
newPassword
string
required
The new plain-text password to set.
​
confirmPassword
string
required
Must match newPassword. The server validates equality before updating.

​
Response

​
message
string
Confirmation that the password was updated.
cURL
curl -X POST https://your-backend-domain.com/api/auth/update-new-password \
  -H "Content-Type: application/json" \
  -d '{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "newPassword": "newSecurePassword",
    "confirmPassword": "newSecurePassword"
  }'

​
POST /api/auth/reset-password

Change the password for a logged-in user who knows their current password. Use this for in-app password changes, not forgotten passwords. Auth required: No (validated by supplying the correct currentPassword)

​
Request body

​
email
string
required
Email address of the account.
​
currentPassword
string
required
The user’s existing password. Must match the stored hash.
​
newPassword
string
required
The replacement password.
​
confirmPassword
string
required
Must match newPassword.

​
Response

​
message
string
Confirmation that the password was changed.
cURL
curl -X POST https://your-backend-domain.com/api/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "currentPassword": "oldPassword",
    "newPassword": "newSecurePassword",
    "confirmPassword": "newSecurePassword"
  }'

Build docs developers (and LLMs) love

Get started for freeTalk to us