Refresh Token

Refresh OAuth2 access token using a valid refresh token.

Quick Navigation

• Endpoint
• Headers
• Request Body
• Parameters
• Validations
• Response
• Success (200)
• Error Codes
• Data Flow
• Features
• Token Rotation
• Example
• Related Endpoints

Endpoint

POST /api/v1/auth/refresh-token

Headers

Header	Required	Description
Content-Type	Yes	application/json

Request Body

{
  "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
}

Parameters

Field	Type	Required	Description
refresh_token	string	Yes	Valid refresh token

Validations

• Refresh token format validation
• Refresh token signature verification
• Refresh token expiration check
• Refresh token revocation check
• User account status check

Response

Success (200)

{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
    "token_type": "bearer",
    "expires_in": 3600,
    "message": "Token refreshed successfully"
  },
  "message": "Token refreshed successfully"
}

Error Codes

Status	Code	Description
401	INVALID_REFRESH_TOKEN	Invalid or expired refresh token
401	TOKEN_REVOKED	Refresh token has been revoked
422	VALIDATION_ERROR	Request validation failed

Data Flow

1. Token Validation

   • Verify refresh token signature
   • Check token expiration
   • Extract user ID and token ID

2. Revocation Check

   • Check if token is in revocation list (Redis)
   • Verify token hasn't been revoked

3. User Validation

   • Verify user exists and is active
   • Check account status

4. Token Generation

   • Generate new access token (1 hour expiry)
   • Generate new refresh token (30 days expiry)
   • Include user claims in tokens

5. Token Revocation

   • Add old refresh token to revocation list
   • Set revocation expiry

6. Audit Logging

   • Log token refresh event
   • Record IP address

Features

• Refresh token validation
• New access token and refresh token generation
• Old refresh token revocation (prevents reuse)
• Audit logging
• Automatic token rotation

Token Rotation

The system implements token rotation:

• Old refresh token is revoked immediately
• New refresh token is issued
• This prevents token reuse attacks

Example

curl -X POST https://api.rivergen.com/api/v1/auth/refresh-token \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
  }'

Related Endpoints

• Login - Get initial tokens
• Logout - Revoke tokens