login.mdx

title	Login
description	Authenticate a user with email and password and receive an access token.

POST /api/userAuth/login

Validates the user's credentials and returns a short-lived JWT access token. A refresh token is also issued to keep the session alive without requiring the user to log in again.

Required Header

x-api-key: your pk_live_… key.

Request Body

The user's registered email address. The user's password.

Response Fields

Short-lived JWT. Include this in the `Authorization: Bearer` header for authenticated requests. Human-readable duration until the access token expires (e.g., `"15m"`). MongoDB ObjectId of the authenticated user. The user's email address. The user's name. Any other non-sensitive fields from your `users` collection. The response also includes a `token` field as a backward-compatibility alias of `accessToken`. The `token` alias will be removed in a future release — migrate your clients to `accessToken` now.

Refresh Token Delivery

The refresh token is issued alongside the access token and delivered differently depending on the client type:

• Web (browser): issued as an HTTP-only cookie. Your browser stores and sends it automatically — you do not need to handle it manually.
• Mobile / non-browser: returned in the x-refresh-token response header. Store it securely and include it when calling /api/userAuth/refresh-token.

Code Examples

const res = await fetch('https://api.urbackend.in/api/userAuth/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'pk_live_YOUR_KEY'
  },
  credentials: 'include', // Include for web: stores the refresh cookie
  body: JSON.stringify({
    email: 'alice@example.com',
    password: 'securePassword123'
  })
});

const { accessToken, expiresIn, user } = await res.json();

curl -X POST "https://api.urbackend.in/api/userAuth/login" \
  -H "Content-Type: application/json" \
  -H "x-api-key: pk_live_YOUR_KEY" \
  -c cookies.txt \
  -d '{
    "email": "alice@example.com",
    "password": "securePassword123"
  }'

Success Response

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": "15m",
  "user": {
    "_id": "64fd1234abcd5678ef901234",
    "email": "alice@example.com",
    "name": "Alice"
  }
}

Errors

Status	Cause
400 Bad Request	Missing email or password
401 Unauthorized	Invalid credentials