Skip to main content

​
POST /api/auth/refresh

Exchange a valid refresh token for a new access token. Use this endpoint when your access token expires to maintain authenticated sessions without requiring the user to log in again.

​
Request Body

​
refreshToken
string
required
Valid refresh token received from login or registration

​
Response

​
success
boolean
required
Indicates if the request was successful
​
data
object
​
accessToken
string
New JWT access token for authenticating API requests

​
Error Responses

​
401 Unauthorized - Invalid Token
Returned when the refresh token is invalid, expired, or malformed.
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Refresh token inválido"
  }
}
​
401 Unauthorized - User Not Found
Returned when the user associated with the token no longer exists or is inactive.
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Usuario no encontrado"
  }
}

​
Example Request

curl -X POST https://api.restai.com/api/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

​
Example Response

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

​
Token Lifecycle

  1. Initial Authentication: User logs in and receives both access and refresh tokens
  2. API Requests: Client uses access token in Authorization header
  3. Token Expiration: When access token expires, API returns 401
  4. Token Refresh: Client calls this endpoint with refresh token to get new access token
  5. Continue: Client continues making requests with new access token

​
Best Practices

  • Store refresh tokens securely (httpOnly cookies or secure storage)
  • Implement automatic token refresh before access token expires
  • Handle 401 errors by attempting to refresh before prompting re-login
  • Refresh tokens are valid for 7 days from issuance
  • Logging out invalidates all refresh tokens for the user

Build docs developers (and LLMs) love

Get started for freeTalk to us