> ## Documentation Index
> Fetch the complete documentation index at: https://rideshare.docs.sumit-dhondikar.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Refresh Token

> Exchange a valid refresh token for a new access token and a rotated refresh token.

Use your existing refresh token to obtain a new access token and a replacement refresh token. This lets you keep users authenticated without requiring them to log in again.

## Request

**`POST /auth/refresh`**

<ParamField body="refreshToken" type="string" required>
  The refresh token issued during login or the previous token rotation.
</ParamField>

## Response

<ResponseField name="accessToken" type="string">
  The newly issued JWT access token.
</ResponseField>

<ResponseField name="refreshToken" type="string">
  A new refresh token to use in future rotation requests. Replace the token you previously stored with this one.
</ResponseField>

<ResponseField name="tokenType" type="string">
  Always `"Bearer"`.
</ResponseField>

<ResponseField name="expiresIn" type="number">
  Number of seconds until the new access token expires.
</ResponseField>

<ResponseField name="name" type="string">
  The display name of the authenticated user.
</ResponseField>

<ResponseField name="role" type="string">
  The effective role associated with this token pair.
</ResponseField>

<ResponseField name="id" type="number">
  The numeric ID of the authenticated user.
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST http://localhost:8080/auth/refresh \
    -H "Content-Type: application/json" \
    -d '{"refreshToken": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4..."}'
  ```

  ```json Response theme={null}
  {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "bmV3UmVmcmVzaFRva2Vu...",
    "tokenType": "Bearer",
    "expiresIn": 900,
    "name": "Alex",
    "role": "USER",
    "id": 42
  }
  ```
</CodeGroup>

<Note>
  Each refresh token can only be used once. After a successful rotation, the old `refreshToken` is immediately invalidated. Always save the new `refreshToken` from the response before discarding the previous one.
</Note>

## Error codes

| Status | Meaning                                                            |
| ------ | ------------------------------------------------------------------ |
| 400    | `refreshToken` is missing or blank                                 |
| 401    | The refresh token is invalid, expired, or has already been revoked |