# Route Spec

## Route ID
`auth-session-refresh`

## Endpoint
`POST /api/v1/auth/session/refresh`

## Human Description
Renews access token using refresh token so users stay signed in after app restart or token expiry.

## Authentication
- Required: `no` (refresh token acts as credential)
- Auth type: `refresh token`
- Required roles/scopes: `none`

## Request
### Headers
- `Content-Type: application/json`

### Body
```json
{
  "refreshToken": "jwt_refresh_token"
}
```

## Responses
### Success: `200 OK`
When returned:
- Refresh token is valid and not revoked.

Body:
```json
{
  "success": true,
  "message": "Session refreshed",
  "data": {
    "accessToken": "new_jwt_access_token",
    "refreshToken": "rotated_refresh_token",
    "accessTokenExpiresAt": "2026-02-18T14:34:56Z"
  }
}
```

### Error: `401 Unauthorized`
When returned:
- Refresh token expired, invalid, or revoked.

Body:
```json
{
  "success": false,
  "error": {
    "code": "REFRESH_TOKEN_INVALID",
    "message": "Session expired. Please log in again.",
    "details": {}
  }
}
```

## Data & Caching Dependencies
- **Spanner Tables:** `None`
- **Redis Cache:** `refresh_tokens (Read/Delete)`
- **GCS Storage:** `None`
- **Edge Cache (CDN):** `No`

## Side Effects
- Rotates refresh token on success.