Token Lifecycle & Security
Comprehensive overview of cryptographic token issuance, expiration logic, silent rotation protocols, and strict storage compliance.
Cryptographic Issuance
Upon successful resolution of the OAuth2 PKCE handshake, your backend is issued a cryptographic token pair: an Access Token and a Refresh Token. The access token is a stateless JSON Web Token (JWT) authorizing AI inference requests.
| Primitive | Functionality | Lifespan |
|---|---|---|
| Access Token | Authorizes high-throughput AI API requests | Short-lived (Strict TTL) |
| Refresh Token | Cryptographic key used to silently mint new Access Tokens | Long-lived (Rolling TTL) |
Expiration & Rotation
To mitigate token exfiltration risks, Access Tokens are intentionally short-lived. When a token expires, the rNet proxy will aggressively reject subsequent AI requests with a 401 Unauthorized status. Your backend infrastructure must detect this and silently rotate the token.
Silent Rotation Protocol
1
TTL Expiration Detection
Preemptively monitor the
expires_in payload from the token issuance, or passively catch 401 responses from the AI gateway.2
Invoke Rotation Endpoint
Execute the SDK's
refreshAccessToken() primitive, passing the securely stored Refresh Token.3
State Synchronization
Atomically update the user's session with the newly minted Access Token. rNet may also issue a rotated Refresh Token depending on threat heuristics.
javascript
// Silent Token Rotation Route
app.post('/refresh', async (req, res) => {
try {
const tokens = await auth.refreshAccessToken(
req.session.rnet.refreshToken
);
// Atomically synchronize session
req.session.rnet.accessToken = tokens.access_token;
if (tokens.refresh_token) {
req.session.rnet.refreshToken = tokens.refresh_token;
}
res.json({ status: 'rotated' });
} catch (err) {
// Hard failure: Refresh token invalidated. Force re-authentication.
req.session.rnet = null;
res.status(401).json({ error: 'Session terminated. Re-authentication required.' });
}
});Failure Scenarios
| State | Resolution Strategy |
|---|---|
| Access token TTL expired | Execute Silent Rotation via Refresh Token |
| Refresh token TTL expired | Purge session, redirect to OAuth gateway |
| Token cryptographically invalid | Purge session, redirect to OAuth gateway immediately |
| AI proxy returns 401 | Attempt one (1) silent rotation. If failed, purge session. |
Storage Compliance & Hardening
- Backend Isolation: Tokens must reside exclusively within secure server-side sessions or encrypted cookies.
- Web Storage Prohibition: Never write tokens to
localStorageorsessionStoragedue to severe XSS vulnerability profiles. - Cookie Hardening: Enforce
HttpOnly,Secure, andSameSite=Lax/Strictdirectives globally. - Termination Protocol: Actively destroy sessions and purge cookies upon user sign-out.
javascript
// Cryptographically Hardened Cookie Configuration
res.cookie('rnet_session', encryptedSessionState, {
httpOnly: true,
secure: process.env.NODE_ENV === 'production', // Require TLS
sameSite: 'lax', // Mitigate CSRF
maxAge: 3600000 // Strict 1-hour TTL
});Critical Vulnerability Warning
Exposing the
Client Secret, Access Token, or Refresh Token to the client-side bundle constitutes a critical security vulnerability. All cryptographic handshakes must occur on your isolated backend.Session Termination (Sign Out)
Upon user sign-out, your application must comprehensively purge all local authentication states.
Termination Sequence
1
Purge Backend State
Atomically destroy the server-side session entity containing the rNet tokens.
2
Invalidate Client State
Clear all associated session cookies (e.g.,
rnet_session, pkce_state).3
Route to Unauthenticated State
Redirect the user to the public landing page. Subsequent access requires a fresh PKCE handshake.
javascript
app.get('/logout', (req, res) => {
// Purge token state
req.session.rnet = null;
// Invalidate client cookies
res.clearCookie('rnet_session');
res.clearCookie('pkce_state');
// Destroy session entity
req.session.destroy(() => {
res.redirect('/');
});
});Next Module
Understand the economic model in Credit Usage.