Refresh Token
Refresh access tokens using refresh tokens
Refresh Token
Obtain a new access token using a valid refresh token without requiring the user to log in again.
Endpoint
POST /auth/refreshAuthentication: None required (uses refresh token in body)
Request Body
{
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| refresh_token | string | Yes | Valid refresh token from login |
Response
Success (200 OK)
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"access_expires_at": "2024-01-15T10:30:00Z",
"refresh_expires_at": "2024-01-22T09:00:00Z",
"client_id": 123456
}Response Fields
| Field | Type | Description |
|---|---|---|
| access_token | string | New JWT token for API authentication |
| refresh_token | string | New refresh token (rotation enabled) |
| access_expires_at | datetime | Access token expiration timestamp (UTC) |
| refresh_expires_at | datetime | Refresh token expiration timestamp (UTC) |
| client_id | number | Your unique client identifier |
Error Responses
400 Bad Request
{
"error": "validation_error",
"message": "Refresh token is required"
}401 Unauthorized
{
"error": "unauthorized",
"message": "Invalid refresh token"
}Examples
curl -X POST {{host}}/auth/refresh \
-H "Content-Type: application/json" \
-d '{
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}'<?php
$data = [
'refresh_token' => $stored_refresh_token
];
$ch = curl_init('{{host}}/auth/refresh');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$data = json_decode($response, true);
$newAccessToken = $data['access_token'];
curl_close($ch);
?>Best Practices
- Proactive Refresh: Refresh tokens before they expire (e.g., 5 minutes early)
- Error Handling: Always handle refresh failures and redirect to login
- Token Rotation: If a new refresh token is provided, store it immediately
- Secure Storage: Store refresh tokens securely (HttpOnly cookies recommended)
- Retry Logic: Implement automatic retry for 401 responses after refresh