Token Refresh & Rotation

Refresh a time-bound grant, retry a lost refresh response, see rotation refuse old refresh tokens, and hit the expiry boundary.

Overview

The example takes one grant through its refresh lifecycle and lets a second grant expire:

1. Authorize a grant with an expiresIn lifetime (GRANT_TTL, default 5m).
2. Verify the grant token locally against the JWKS and with the service.
3. Refresh. The new grant token keeps the grantId; the grant’s expiresAt stays the same.
4. Verify again with the refreshed token.
5. Retry a lost response. Sending the first refresh token again at once returns the refresh token it was already rotated to.
6. Rotation. After the rotated refresh token is used, the first one is refused.
7. Expiry. A second grant with a short lifetime (EXPIRED_GRANT_TTL, default 3s) lapses; its token stops verifying and refresh is refused, so a new authorization is required.

Prerequisites

• Node.js 24 LTS
• Docker with Compose

Run

From the repository root, start the local stack:

docker compose up --build

Then, in another terminal:

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

Sample output

=== Grant Refresh Lifecycle ===

Agent: ag_01...

--- Grant valid for 5m ---
  grantId       grnt_01...
  scopes        calendar:read, email:send
  expiresAt     2026-10-20T22:46:48.858Z
  refreshToken  ref_01...

--- Verify the first grant token ---
  local (JWKS)  ok, principal user-alice, scopes calendar:read, email:send
  service       valid=true

--- Refresh ---
  grantId       grnt_01... (unchanged)
  expiresAt     2026-10-20T22:46:48.858Z (refresh does not extend the grant)

--- Recover a lost refresh response ---
  same rotated refresh token returned: true

--- Rotation moves on ---
  refused: Refresh token already used

--- Grant valid for 3s, left to expire ---
  waiting 5s...
  service       valid=false (expected false)
  refresh refused: Grant has expired

Refresh lifecycle complete.

Configuration

Variable	Default	Meaning
GRANTEX_URL	http://localhost:3001	Auth service base URL
GRANTEX_API_KEY	sandbox-api-key-local	API key; a sandbox key approves consent automatically, which the script relies on
GRANT_TTL	5m	Lifetime of the grant that is refreshed
EXPIRED_GRANT_TTL	3s	Lifetime of the grant that is left to expire
TOKEN_TTL	unset	Older name for EXPIRED_GRANT_TTL, still read when that is unset

Retrying a lost refresh response

If the service commits a rotation but the client never receives the reply, the client can send the same refresh token again, with the same Idempotency-Key, within five minutes and receive the refresh token it was rotated to. Recent SDK releases reuse the key for such a retry automatically. Once the rotated refresh token has been used, the earlier one is refused. Refresh never extends the grant: after expiresAt the agent needs a new authorization.

Source code

See 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].