Token Refresh & Rotation

Active-grant refresh rotation, lost-response recovery, and the expired-grant re-authorization boundary.

What it does

This example demonstrates the complete token refresh lifecycle:

1. Authorize an active grant using the expiresIn parameter
2. Use the token successfully while the grant remains active (local JWKS-based + online verification)
3. Refresh the token — get a new JWT and rotated refresh token with the same grantId and expiresAt
4. Use the refreshed token — verify it works with full scope access
5. Refresh response recovery — retry the previous refresh token immediately to recover the already-rotated token
6. Refresh token rotation — demonstrate that old refresh tokens cannot keep being reused
7. Expired grant boundary — demonstrate that an expired grant must be re-authorized rather than refreshed

Prerequisites

• Node.js 24 LTS (the tested repository toolchain)
• Docker (Docker Desktop or Docker Engine with Compose)

Run

Start the local Grantex stack from the repository root:

docker compose up --build

In a separate terminal, run the example:

cd examples/token-expiry-refresh
npm install
npm start

Expected output

=== Token Refresh & Rotation Demo ===

Agent registered: ag_01HXYZ...

--- Authorizing an active grant (5m) ---
Grant token received:
  grantId:      grnt_01...
  scopes:       calendar:read, email:send
  expiresAt:    2026-03-30T12:05:00.000Z
  refreshToken: ref_01HXYZ...

--- Using token before expiry ---
Offline verification: PASSED
Online verification:  valid = true

--- Refreshing token ---
Token refreshed successfully!
  grantId:   grnt_01... (same as original)
  expiresAt: 2026-03-30T12:05:00.000Z (grant lifetime unchanged)
  scopes:    calendar:read, email:send

--- Using refreshed token ---
Offline verification: PASSED
Online verification:  valid = true

--- Refresh response recovery window ---
Retrying the original refresh token immediately (simulates a lost HTTP response)...
Recovered refresh token matches first rotation: true

--- Refresh token rotation (single-use enforcement) ---
Advancing the rotation chain with the current refresh token...
Attempting to reuse the original refresh token after the chain moved forward...
Blocked! Original refresh token rejected.
  Reason: Refresh tokens are single-use; recovery only works before the rotated child is used.

--- Expired grant boundary ---
Creating a short-lived grant (3s) to show the re-authorization boundary...
Waiting 5s for the grant to expire...
Online verification after expiry: valid = false (expected: false)
Refresh after grant expiry blocked.
  Reason: Refresh rotates credentials for an active grant; expired grants require re-authorization.

Done! Token refresh lifecycle complete.

Environment variables

Variable	Default	Description
GRANTEX_URL	http://localhost:3001	Base URL of the Grantex auth service
GRANTEX_API_KEY	sandbox-api-key-local	API key. Use a sandbox key for auto-approval
GRANT_TTL	5m	Active grant lifetime used for refresh rotation
EXPIRED_GRANT_TTL	3s	Short grant lifetime used only for the expired-grant boundary check
TOKEN_TTL	unset	Backward-compatible alias for EXPIRED_GRANT_TTL

Refresh boundary

expiresIn controls the underlying grant lifetime. Refresh rotates credentials for that active grant and does not extend the grant’s expiresAt. If the refresh response is lost after the server commits rotation, retry the previous refresh token immediately; Grantex can return the already-rotated refresh token during the five-minute recovery window. After the grant expires, the caller must re-authorize.

Source code

The full source is in examples/token-expiry-refresh/src/index.ts.

Ownership

Grantex is owned by Orchestrum Technologies LLP. Inventor and owner: Sanjeev Kumar. Ownership contact: [e-mail] or [e-mail].