Refresh Session

​

Endpoint

POST /recipe/session/refresh

​

Request Body

​

Response

​

Success Response

​

Error Responses

​

Example Request

curl -X POST https://your-domain.com/recipe/session/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "def456...",
    "antiCsrfToken": "anti-csrf-token-value",
    "enableAntiCsrf": true,
    "useDynamicSigningKey": true
  }'

​

Example Responses

​

Successful Refresh

{
  "status": "OK",
  "session": {
    "handle": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "userId": "user123",
    "recipeUserId": "user123",
    "userDataInJWT": {
      "role": "admin",
      "email": "[email protected]"
    },
    "tenantId": "public"
  },
  "accessToken": {
    "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiry": 1640003600000,
    "createdTime": 1640000000000
  },
  "refreshToken": {
    "token": "ghi789...",
    "expiry": 1648003600000,
    "createdTime": 1640000000000
  },
  "antiCsrfToken": "new-anti-csrf-token-value"
}

​

Unauthorized Response

{
  "status": "UNAUTHORISED",
  "message": "Session missing in db or has expired"
}

​

Token Theft Detected

{
  "status": "TOKEN_THEFT_DETECTED",
  "session": {
    "handle": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "userId": "user123",
    "recipeUserId": "user123"
  }
}

​

Implementation Details

​

Source Code Reference

• API Handler: View source
• Session Logic: View source

​

Refresh Process

1. Validate Refresh Token - Decrypts and verifies the refresh token structure
2. Check Anti-CSRF - Validates anti-CSRF token if enabled
3. Database Transaction - Atomic operation to prevent race conditions
4. Verify Token Chain - Checks refresh token hash matches database
5. Detect Token Theft - Identifies if an old refresh token was reused
6. Rotate Tokens - Creates new access and refresh tokens
7. Update Database - Stores new refresh token hash
8. Update Active Users - Records user activity timestamp

​

Token Rotation

1. Each refresh creates a new refresh token
2. The old refresh token becomes invalid
3. New tokens include reference to parent token hash
4. Database tracks the current valid refresh token hash

​

Token Theft Detection

1. A refresh token is used that doesn’t match the current valid token in the database
2. The token also doesn’t match the parent token (normal rotation scenario)
3. This indicates an old token was stolen and reused

• All sessions for the user are immediately revoked
• TOKEN_THEFT_DETECTED response is returned
• The session handle and user IDs are provided for logging

​

Security Considerations

​

Token Rotation Security

​

Anti-CSRF Protection

​

Token Theft Response

1. Log the Event - Record session handle, user ID, IP address, and timestamp
2. Alert Security - Notify security monitoring systems
3. User Notification - Consider emailing the user about suspicious activity
4. Force Logout - Clear all client-side session data
5. Require Re-authentication - User must log in again

​

Common Use Cases

​

Automatic Token Refresh

// Refresh tokens when access token expires
async function refreshSession(refreshToken, antiCsrfToken) {
  const response = await fetch('https://your-domain.com/recipe/session/refresh', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      refreshToken,
      antiCsrfToken,
      enableAntiCsrf: true,
      useDynamicSigningKey: true
    })
  });
  
  const data = await response.json();
  
  if (data.status === 'OK') {
    // Update stored tokens
    localStorage.setItem('accessToken', data.accessToken.token);
    localStorage.setItem('refreshToken', data.refreshToken.token);
    localStorage.setItem('antiCsrfToken', data.antiCsrfToken);
    return true;
  } else if (data.status === 'TOKEN_THEFT_DETECTED') {
    // Security breach detected
    console.error('Token theft detected!', data.session);
    logout();
    return false;
  } else {
    // Unauthorized - session expired or invalid
    logout();
    return false;
  }
}

​

Handling Refresh in API Calls

// Retry API call after refreshing tokens
async function apiCallWithRefresh(url, options) {
  let response = await fetch(url, options);
  
  // If access token expired, try to refresh
  if (response.status === 401) {
    const refreshed = await refreshSession(
      localStorage.getItem('refreshToken'),
      localStorage.getItem('antiCsrfToken')
    );
    
    if (refreshed) {
      // Retry with new access token
      options.headers['Authorization'] = `Bearer ${localStorage.getItem('accessToken')}`;
      response = await fetch(url, options);
    }
  }
  
  return response;
}

​

Error Handling

​

Unauthorized Errors

• Refresh token has expired
• Session was revoked
• Refresh token is invalid or corrupted
• Anti-CSRF token doesn’t match
• Session not found in database

​

Token Theft Detection

• Old refresh token was reused after new one was issued
• Indicates potential token theft or client-side storage issues

1. Clear all session data
2. Log security event
3. Show security alert to user
4. Redirect to login

​

Best Practices

1. Refresh Proactively - Refresh tokens before access token expires (e.g., 5 minutes before)
2. Handle Failures Gracefully - On refresh failure, log out user rather than retrying
3. Secure Storage - Store refresh tokens in httpOnly cookies or secure storage
4. Monitor Theft Detection - Alert on TOKEN_THEFT_DETECTED responses
5. Update Atomically - Update all tokens (access, refresh, anti-CSRF) together
6. Rate Limit - Implement rate limiting to prevent refresh token brute force

​

CDI Version Compatibility

• CDI < 2.21: Returns idRefreshToken in response
• CDI >= 2.21: idRefreshToken removed from response
• CDI >= 3.0: useDynamicSigningKey parameter available, tenantId in response
• CDI >= 4.0: recipeUserId included in session response
• CDI >= 5.0: useDynamicSigningKey defaults to null instead of true