Refresh Driver Access Token
# Refresh Driver Access Token
Refreshes an expired or expiring driver JWT access token using a valid refresh token.
> **🔒 Refresh Token Rotation:** Every refresh operation securely revokes the submitted refresh token and generates a brand new token pair (`accessToken` and `refreshToken`). If an already-revoked token is submitted or the driver has logged in on another device, the request is rejected with `SESSION_REVOKED`.
---
### Endpoint Overview
- **Method:** `POST`
- **Route:** `/api/v1/driver/auth/refresh`
- **Authentication:** `None (Refresh Token in Body)`
- **Content-Type:** `application/json`
---
### Request Headers
| Header | Type | Required | Description |
| --- | --- | --- | --- |
| `Content-Type` | `string` | **Yes** | Must be `application/json` |
| `User-Agent` | `string` | No | Client device info (used for session tracking) |
| `X-Forwarded-For` | `string` | No | Client IP address (used for session logging) |
---
### Request Body Schema
| Field | Data Type | Required | Default | Allowed Values / Constraints | Description |
| --- | --- | --- | --- | --- | --- |
| `refreshToken` | `string` | **Yes** | — | Min length 1 (prefixed with `drtok_`) | Active refresh token previously received |
| `deviceId` | `string` | No | `null` | Any string | Optional device identifier |
#### Example Request Body
``` json
{
"refreshToken": "drtok_7f8e9d0c1b2a345678901234567890ab",
"deviceId": "d1234567-89ab-cdef-0123-456789abcdef"
}
```
---
### Response Body Schema (`200 OK`)
| Top-Level Key | Data Type | Description |
| --- | --- | --- |
| `message` | `string` | Confirmation message (`"Driver tokens refreshed successfully"`) |
| `accessToken` | `string` | New JWT access token (valid for 15m–1h) |
| `refreshToken` | `string` | Brand new rotated refresh token string (valid for 30 days) |
---
### Response Examples
#### 1\. `200 OK` — Tokens Rotated Successfully
``` json
{
"message": "Driver tokens refreshed successfully",
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJkcnZfOGE3YjZjNWQ0ZSIsInNlc3Npb25fdmVyc2lvbiI6MSwiaWF0IjoxNzU4NDMzNTAwLCJleHAiOjE3NTg0MzcxMDB9.EXAMPLE_SIGNATURE",
"refreshToken": "drtok_8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d"
}
```
#### 2\. `401 Unauthorized` — Session Revoked (Concurrent Login on Another Device)
``` json
{
"error": "SESSION_REVOKED",
"message": "Your session has been terminated because you logged in on another device."
}
```
#### 3\. `401 Unauthorized` — Invalid or Expired Refresh Token
``` json
{
"error": "Unauthorized",
"message": "Refresh token has expired"
}
```
Or:
``` json
{
"error": "Unauthorized",
"message": "Invalid refresh token"
}
```
#### 4\. `400 Bad Request` — Validation Error (Missing `refreshToken`)
``` json
{
"success": false,
"message": "Validation failed: refreshToken: Refresh token is required",
"errors": [
{
"field": "refreshToken",
"message": "Refresh token is required"
}
]
}
```
---
### Status Codes Reference
| HTTP Status Code | Condition |
| --- | --- |
| **`200 OK`** | Token rotated successfully; new access and refresh tokens returned. |
| **`400 Bad Request`** | Missing or empty `refreshToken` in request body. |
| **`401 Unauthorized`** | Token expired, invalid, or revoked due to another device login (`SESSION_REVOKED`). |
Authentication
AuthorizationBearer
Bearer authentication of the form Bearer <token>, where token is your auth token.