refresh-token.mdx

title	Refresh Token
description	Exchange a valid refresh token for a new access token without requiring the user to log in again.

POST /api/userAuth/refresh-token

Issues a new access token using the current refresh token. The refresh token is automatically rotated — the old one is invalidated and a new one is issued.

Call this endpoint whenever you receive a `401 Unauthorized` response on any other request. It is safe to call proactively when the access token is about to expire.

Required Header

x-api-key: your pk_live_… key.

Two Modes

Depending on your client type, you send the refresh token differently.

Web (browser)

The refresh token is stored in an HTTP-only cookie set during login. You do not need to read or send it manually — just include credentials: 'include' so the browser attaches the cookie automatically.

Mobile / non-browser

Include the refresh token in the x-refresh-token header, and set x-refresh-token-mode to 'header' to tell urBackend to read it from there.

Response Fields

Response Fields

The new short-lived JWT access token. Human-readable duration until the new access token expires (e.g., `"15m"`).

Code Examples

// Browser: credentials: 'include' sends the HTTP-only cookie automatically
const res = await fetch('https://api.urbackend.in/api/userAuth/refresh-token', {
  method: 'POST',
  headers: {
    'x-api-key': 'pk_live_YOUR_KEY'
  },
  credentials: 'include'
});

const { accessToken: newAccessToken } = await res.json();

// Mobile / non-browser: pass the refresh token explicitly in a header
const res = await fetch('https://api.urbackend.in/api/userAuth/refresh-token', {
  method: 'POST',
  headers: {
    'x-api-key': 'pk_live_YOUR_KEY',
    'x-refresh-token': storedRefreshToken,
    'x-refresh-token-mode': 'header'
  }
});

const { accessToken: newAccessToken } = await res.json();
// Persist the new refresh token returned in the x-refresh-token response header

Success Response

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": "15m"
}

Errors

Status	Cause
401 Unauthorized	Refresh token missing, invalid, or already rotated