Authenticate with the Yeti Jobs API

The Yeti Jobs API uses JWT authentication via HTTP-only cookies. The full flow is four steps: create an account, verify your email address with a 6-digit code, log in to receive the token cookie, then attach that cookie to every subsequent request. Password reset follows a parallel verify-by-code pattern and is rate-limited to protect against abuse.

The /api/v1/users/verify, /api/v1/users/verify/resend, /api/v1/users/forget-password, and /api/v1/users/forget-password/verify endpoints are all rate-limited to 2 requests per minute. Exceeding this returns 429 Too Many Requests with the message "You only can send resend request twice per minute". Plan retry logic accordingly.

Authentication Flow

Create a new account by sending your name, education level, email, and password. The account role is assigned automatically by the server — all new accounts default to guest (job seeker). An admin must later change the role to recruiter if required.

Field	Type	Required	Notes
`fname`	string	Yes	First name, minimum 2 characters
`lname`	string	Yes	Last name, minimum 2 characters
`education`	string	Yes	One of: `Basic`, `Matrix`, `High School`, `Undergraduation`, `Postgraduation`
`email`	string	Yes	Must be a valid email with a resolvable mail domain
`password`	string	Yes	Must satisfy the server-side password regex

Request

curl -s -X POST https://yeti-jobs.onrender.com/api/v1/users/signup \
  -H "Content-Type: application/json" \
  -d '{
    "fname": "Jane",
    "lname": "Doe",
    "education": "Undergraduation",
    "email": "jane@example.com",
    "password": "SecurePass123!"
  }'

Response 201 Created

{
  "message": "Succssfully Signed Up, Verification Code have been sent to your mail"
}

The server immediately dispatches a 6-digit verification code to the email address you provided and sets a temporary token cookie marking the session as unverified. You cannot perform authenticated actions until the email is confirmed.

fname and lname are stored separately in the database. Both fields are required and are validated server-side with Zod before the record is created. The role field is not accepted at signup — the server assigns it automatically.

Verify Your Email

After signup the server sends a 6-digit numeric code to your email. Submit that code to activate your account. This endpoint requires you to be logged in as an unverified user — the isUnverifiedUser middleware enforces this.Request

curl -s -X POST https://yeti-jobs.onrender.com/api/v1/users/verify \
  -H "Content-Type: application/json" \
  --cookie 'token=YOUR_JWT' \
  -d '{
    "code": 123456
  }'

Response 200 OK

{
  "message": "Verification Code Have Been Succssfully Verified"
}

Didn’t receive the code? Resend it with:

curl -s -X POST https://yeti-jobs.onrender.com/api/v1/users/verify/resend \
  -H "Content-Type: application/json" \
  --cookie 'token=YOUR_JWT'

Both /verify and /verify/resend share the 2 requests-per-minute rate limit. Do not trigger retries in a tight loop.

Exchange your email and password for a JWT stored in an HTTP-only cookie. The alreadyLoggedIn middleware will reject this call with 400 if you already have a valid session cookie — log out first if you need to switch accounts.Request

curl -s -X POST https://yeti-jobs.onrender.com/api/v1/users/login \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{
    "email": "jane@example.com",
    "password": "SecurePass123!"
  }'

Response 200 OKThe server sets the token HTTP-only cookie and returns a confirmation message:

{
  "message": "Succssfully Logged In"
}

The -c cookies.txt flag tells curl to save the Set-Cookie header to a file. Pass -b cookies.txt on future requests to replay the cookie automatically, or extract the token value and pass it with --cookie 'token=VALUE'.

Make Authenticated Requests

With the cookie in hand, every subsequent request to a protected route is automatically credentialed.Browser / frontend — the cookie is sent automatically because CORS credentials are enabled server-side (credentials: true).curl / API clients — attach the cookie explicitly on every call:

# Using a saved cookie jar (recommended for scripting)
curl -s https://yeti-jobs.onrender.com/api/v1/users/login-status \
  -b cookies.txt

# Passing the token value directly
curl -s https://yeti-jobs.onrender.com/api/v1/users/login-status \
  --cookie 'token=YOUR_JWT'

Response 200 OK (login-status check)

{
  "message": {
    "uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "role": "guest",
    "company_id": null,
    "verify": true
  },
  "url": null
}

Log out to clear the cookie server-side:

curl -s https://yeti-jobs.onrender.com/api/v1/users/logout \
  -b cookies.txt

Password Reset Flow

If a user forgets their password, a two-step verify-by-code flow resets it without requiring an existing session.

Request a Reset Code

Submit the account’s email address. If the address matches a registered user the server sends a 6-digit reset code by email.Request

curl -s -X POST https://yeti-jobs.onrender.com/api/v1/users/forget-password \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com"
  }'

Response 201 Created

{
  "message": "The password Have Beeen forget you can check your email for verify your code."
}

This endpoint is rate-limited to 2 requests per minute. Repeated calls within the window return 429 Too Many Requests. Wait at least 60 seconds before retrying.

Verify the Code and Set a New Password

Submit the reset code, the account email, and the new password together. The endpoint validates the code’s expiry and verified_type before committing the change.

Field	Type	Required	Notes
`code`	number	Yes	The 6-digit code sent to your email
`email`	string	Yes	The email address of the account being reset
`newpassword`	string	Yes	The replacement password

Request

curl -s -X POST https://yeti-jobs.onrender.com/api/v1/users/forget-password/verify \
  -H "Content-Type: application/json" \
  -d '{
    "code": 123456,
    "email": "jane@example.com",
    "newpassword": "NewPass123!"
  }'

Response 201 Created

{
  "message": "You: Jane, Doe Password have been updated"
}

After a successful reset, proceed to Step 3 — Log In with the new password to obtain a fresh session cookie.

Token Lifetime and Expiry

The JWT lifetime is controlled by the MAXAGE environment variable on the server. The token is signed with the JSON_SECRET_KEY environment variable. When the token expires, protected routes return 401 Unauthorized and the client must log in again to receive a new cookie.

Role-Based Access at a Glance

Role	Description	Key permissions
`guest`	Job seeker — assigned automatically on signup	Browse & search jobs, apply, bookmark, manage own profile
`recruiter`	Company employee — assigned by an admin	Create / edit / delete jobs, view applicants, change applicant status, access company dashboard (requires admin to assign company first)
`admin`	Platform administrator	All recruiter actions + assign users to companies, delete companies, access admin dashboard

Routes enforce roles via dedicated middleware (isAdmin, isJobSeeker, isOwnerMiddleware). Attempting an action outside your role returns 403 Forbidden.

Common Authentication Errors

Response	Cause
`401 Unauthorized`	No `token` cookie present, or the JWT has expired
`403 Forbidden`	Cookie is valid but the user’s role is not permitted for this route
`400 Bad Request`	Calling `/login` or `/signup` while already authenticated (blocked by `alreadyLoggedIn` middleware)
`429 Too Many Requests`	More than 2 verify / reset requests within 60 seconds

Overview

Endpoints

Authenticate with the Yeti Jobs API

Authentication Flow

Password Reset Flow

Token Lifetime and Expiry

Role-Based Access at a Glance

Common Authentication Errors

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​Authentication Flow

​Password Reset Flow

​Token Lifetime and Expiry

​Role-Based Access at a Glance

​Common Authentication Errors

Build docs developers (and LLMs) love

Authentication Flow

Password Reset Flow

Token Lifetime and Expiry

Role-Based Access at a Glance

Common Authentication Errors